Runs
Start, list, inspect, cancel, and resume agent, task, and workflow runs, follow their events, answer their input requests, and find the runs that schedules, webhooks, and evaluations start.Lifecycle
Create, list, get, cancel, pause, and resume runs, and read account run analytics.| Operation | Description |
|---|---|
activeAgentRun | Returns the active agent run for a conversation. |
agentRun | Returns an agent run for a conversation. |
agentRuns | Lists agent runs associated with a conversation. |
getRun | Read a run through the canonical Runs query use case. |
listConversationRuns | List readable runs in a conversation. |
listProjectRuns | List readable runs in a project with the target filters and pagination. |
listRuns | List readable account runs with the canonical target filters and pagination. |
projectRuns | Project runs, as REST GET /projects/{project_reference}/runs, with the same filters and values. |
run | A run of any kind, as REST GET /runs/{run_id}. |
cancelRun | Cancel an agent, workflow or task run and every active descendant, as REST POST /runs/{run_id}/cancel. |
createRun | Start a run of any kind, as REST POST /runs. |
deleteRun | Delete an eligible terminal run through its authorized owning use case. |
pauseRun | Pause an agent, task or workflow run at its next safe boundary, as REST POST /runs/{run_id}/pause. |
resumeRun | Resume a supported waiting run, as REST POST /runs/{run_id}/resume. |
updateRun | Update a run’s title or labels using the If-Match request header. |
Events
Read, summarize, and stream run events, and list the event types.| Operation | Description |
|---|---|
agentRunEvents | Returns the agent run’s event history after applying the requested cursor. |
agentRunSnapshot | Returns the current replay snapshot for an agent run’s event stream. |
getRunEvent | Read a run event with its canonical envelope and payload. |
getRunEventsSummary | Summarize visible run events over the selected time window. |
getRunSnapshot | Read the canonical snapshot of visible run events. |
listRunEvents | List run events with the shared visibility policy, filters and event cursor. |
listRunEventTypes | List the public run event types and their payload schemas. |
runEvent | One run event, as REST GET /runs/{run_id}/events/{event_id}. |
runEvents | A page of a run’s events, as REST GET /runs/{run_id}/events. |
runEventSummary | Event counts, as REST GET /runs/{run_id}/events/summary, with the same filters. |
runEventTypes | The run event catalog, as REST GET /runs/event-types. |
runSnapshot | The replay snapshot of an agent run with or without a conversation, as REST GET /runs/{run_id}/snapshot. |
Input requests
Create, find, cancel, and respond to the input requests a run waits for.| Operation | Description |
|---|---|
getInputRequest | Read an input request and its redacted response through its owning use case. |
inputRequest | Returns a structured input request for a conversation. |
inputRequests | Lists structured input requests associated with a conversation. |
listConversationInputRequests | List readable input requests in a conversation. |
listRunInputRequests | List readable input requests of a run through its owning use case. |
runInputRequest | One input request of a run, as REST GET /runs/{run_id}/input-requests/{input_request_id}. |
runInputRequests | A run’s input requests with or without a conversation, as REST GET /runs/{run_id}/input-requests. |
cancelInputRequest | Cancels an open input request. |
createInputRequest | Creates a structured request for human input within a conversation. |
createRunInputRequest | Create an input request for a run. |
submitInputResponse | Submits a human response to an open input request. |
submitRunInputResponse | Respond to a run input request, as REST POST /runs/{run_id}/input-requests/{input_request_id}/responses. |
Children
List the child runs a run starts.| Operation | Description |
|---|---|
childAgentRuns | Lists every child agent run started by the specified parent run. |
childAgentRunsByParentConversation | Lists child agent runs associated with the parent conversation’s execution history. |
childAgentRunsConnection | Lists child agent runs started by the specified parent run, one page at a time. |
listConversationChildRuns | List readable child runs in a conversation. |
listRunChildRuns | List readable child runs of a run. |
runChildren | Lists independently readable direct children of any supported parent run, in canonical REST order. |
Triggers
Start runs from schedules, webhooks, and evaluations, and list the runs they started.| Operation | Description |
|---|---|
listProjectWebhookRuns | List the runs started by a project webhook. |
projectWebhookRuns | A webhook definition’s runs, newest first by default, as REST GET /projects/{project_reference}/webhooks/{webhook_definition_id}/runs. |
createScheduledRun | Start a run from a schedule now, as REST POST /projects/{project_reference}/schedules/{schedule_id}/runs. |
runWebhook | Starts execution from a project webhook definition. |
Queries
| Operation | Description |
|---|---|
agentPushRuntimeServices | Lists registered agent runtime services visible in the selected scope. |
agentWorkers | Lists agent workers connected to a project. |
conversation | Returns a conversation by ID. |
conversationReadState | Returns the current user’s read state for a conversation. |
conversations | Lists conversations visible to the current user. |
conversationTree | Returns up to 1,000 conversation messages, including branches. |
messageBranches | Lists branches associated with a conversation message. |
projectSchedulesDiscovery | Lists schedule definitions discovered in project source. |
projectWebhook | Returns a project webhook definition, or null when no webhook with that id exists in the project. |
projectWebhooks | Lists webhook definitions for a project. |
projectWebhooksDiscovery | Lists webhook definitions discovered in project source. |
unreadCount | Returns the number of unread messages for the current user in a conversation. |
Mutations
| Operation | Description |
|---|---|
addParticipant | Adds a participant to a conversation. |
archiveConversation | Archives a conversation. |
createConversation | Creates a conversation for messages and related agent runs. |
createWebhook | Creates a project webhook definition. |
deleteConversation | Deletes a conversation. |
deleteMessage | Deletes a conversation message. |
deleteWebhook | Deletes a project webhook definition. |
drainAgentPushRuntimeService | Stops selecting the runtime service for new work. |
editMessage | Updates the content of a conversation message. |
forkAtMessage | Creates a conversation branch from a message. |
markAsRead | Updates the current user’s read position in a conversation. |
removeParticipant | Removes a participant from a conversation. |
replayWebhookEvent | Replays a stored webhook event through its configured target. |
resumeAgentPushRuntimeService | Makes the runtime service available for selection again. |
sendMessage | Adds a user message to a conversation. |
switchBranch | Changes the active message branch for a conversation. |
updateConversation | Updates conversation settings. |
updateWebhook | Updates a project webhook definition. |