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, ensure child runs, and read account run analytics.| Operation | Description |
|---|---|
activeAgentRun | Return the active run. |
agentRun | Return an agent run. |
agentRuns | List conversation agent runs. |
getAccountRunAnalytics | Return account run analytics. |
getRun | Get run details: status, errors, target, timing, token usage and cost, by run UUID or public id. |
listConversationRuns | List conversation runs. |
listProjectRuns | List project runs. |
listRuns | List runs; bound runtimes need own project_id, trigger_type=[“schedule”] and trigger_id. |
cancelRun | Cancel a run. |
createRun | Create a run. |
deleteRun | Delete a run. |
ensureChildAgentRun | Create or recover the child run of a parent run tool call. |
failRun | Fail a run. |
finalizeRun | Finalize a run. |
pauseRun | Pause a run. |
resumeRun | Resume a run. |
succeedRun | Succeed a run. |
updateRun | Update a run. |
Events
Append, read, summarize, and stream run events, and list the event types.| Operation | Description |
|---|---|
canonicalRunEventsV1 | Read canonical run events with durable replay cursors. |
canonicalRunEventTypesV1 | Discover canonical run event types and schema references. |
canonicalRunEventV1 | Read one canonical run event by its durable event id. |
getRunEvent | Read one recorded event by canonical run UUID and numeric event_id. |
getRunEventsSummary | Count run events by type and time bucket without event bodies or usage metrics. |
getRunSnapshot | Read a run replay snapshot by canonical UUID; use event readers for targeted failure analysis. |
listRunEvents | Read run event details: errors, steps, model calls and tool results, paginated by canonical UUID. |
listRunEventTypes | List run event types. |
appendRunEvents | Append run events. |
streamCanonicalRunEventsV1 | Stream canonical run events and resume after a durable cursor. |
streamRunEvents | Stream run events. |
Input requests
Create, find, cancel, and respond to the input requests a run waits for.| Operation | Description |
|---|---|
getInputRequest | Return an input request. |
listConversationInputRequests | List conversation input requests. |
listRunInputRequests | List run input requests. |
cancelInputRequest | Cancel an input request. |
createInputResponse | Respond to input request. |
createRunInputRequest | Create an input request. |
Children
List the child runs a run starts.| Operation | Description |
|---|---|
childAgentRuns | List child agent runs. |
childAgentRunsByParentConversation | List child agent runs. |
childAgentRunsConnection | List child agent runs. |
listConversationChildRuns | List conversation child runs. |
listRunChildRuns | List direct child runs by canonical parent UUID; follow page_info.next for further children. |
Triggers
Start runs from schedules, webhooks, and evaluations, and list the runs they started.| Operation | Description |
|---|---|
listProjectWebhookRuns | List webhook runs. |
webhookEvents | List the events a webhook received, newest first, to check deliveries, manual runs and replays; returns one page of webhook events, each with the run it started, if any, and an event that the filter stopped has the status ignored. |
createScheduledRun | Run a schedule now. |
runWebhook | Send a test payload to a webhook as an external sender posts it, to check its target and filter, also when the webhook is a draft or disabled; returns the webhook event that the call created. |
Runtime
Renew the execution lease, delegate event-writer tokens to child runs, acknowledge cancellation stops and pauses, and read pause checkpoints. A worker or runtime calls these with the credential its claim or dispatch issued.| Operation | Description |
|---|---|
createRunEventToken | Issue a short-lived credential that appends events to a direct child run. |
createRunHeartbeat | Renew the execution lease of the current run generation. |
Queries
| Operation | Description |
|---|---|
connectedAgents | List a project’s connected agents: every push runtime service first, then at most the 50 most recently updated pull workers, with no continuation for the rest. |
conversation | Get one conversation before rendering a thread or to check its status, title and project; returns the conversation with its participants and its current branch head. |
conversationMessage | Get one message of a conversation to refresh a single message, for example after streaming finishes; returns the message. |
conversationMessageBranches | List the child messages of a message, oldest first, which are the alternative continuations that start at it; to show the alternatives to an edited message, list the children of the parent of that message. |
conversationReadState | Get the read cursor and the unread count of the caller for a conversation to show unread badges; returns the last read message and the number of unread messages. |
conversations | List the conversations the caller can read, newest activity first, to build a conversation picker or to find a conversation of a project; returns one page of conversations, filtered by project reference and paged with the returned cursor until it is null. |
schedule | Read one schedule by its ID to inspect its target, cron expression, runtime target, state and last failure; returns the schedule. |
schedules | List the schedules stored for a project, newest first, to find a schedule or check its state and last runs; returns one page of schedules. |
sourceSchedules | List the schedules declared in the source files of a project, a branch or an environment to see what can be activated; returns every declared schedule as one page with the discovery diagnostics. |
sourceWebhooks | List the webhooks declared in the source files of a project, a branch or an environment to see what a deployment creates; returns the declared webhooks, the discovery diagnostics and the source files that could not be read, without pagination. |
webhook | Read one webhook by its ID to inspect its target, prompt template, event filter and status; returns the webhook with its public URL and never its secret. |
webhooks | List the webhooks stored for a project, newest first, to find a webhook or its public URL; returns one page of webhooks, or every webhook when neither a limit nor a cursor is sent. |
Mutations
| Operation | Description |
|---|---|
createConversation | Start a conversation in a project when a user or an agent opens a new thread, optionally with a first user message; a retry with the same idempotency key returns the same conversation. |
createConversationMessage | Add a user message to a conversation to send what the user typed; the parent message defaults to the selected branch and an idempotency key makes retries safe. |
createConversationMessageBranch | Create a sibling of a message with new parts when the user edits an earlier message and wants to keep the original reply; the new message gets the parent and role of the original and becomes the selected branch. |
createConversationParticipant | Add a user to a conversation as member or viewer to share a thread; the operation needs the admin relation. |
createSchedule | Create a recurring schedule that starts a task, a workflow or an agent on a cron expression, or, on REST and GraphQL only, activate a schedule declared in source (the MCP tool creates manual schedules only); returns the schedule: a new schedule is active, and a source schedule that was activated before keeps its current status. |
createWebhook | Create a webhook when an external service must start an agent, task or workflow run, or when its deliveries must only be stored as webhook events; returns the webhook and its secret, which is shown only once. |
deleteConversation | Delete a conversation only when the user asks to remove the thread, so that it and its messages are no longer accessible; the deletion cannot be undone through the API and needs the admin relation. |
deleteConversationMessage | Delete one message from a conversation only when the user asks to remove that message; the deletion needs editor access. |
deleteConversationParticipant | Remove a user from a conversation to revoke the access of that participant to the thread; the operation needs the admin relation. |
deleteSchedule | Delete a schedule that is no longer needed so that it starts no more runs; returns the acknowledgement ok: true. |
deleteWebhook | Delete a webhook that is no longer needed so that its URL refuses future deliveries; returns ok true once the webhook is deleted. |
replayWebhookEvent | Send the stored payload of a webhook event to the current target of the webhook again, for example after a failed run; returns the new webhook event that the replay created. |
updateAgentPushRuntimeService | Drain or resume a runtime service. |
updateConversation | Change the title, summary, project or status (active or archived) of a conversation, for example to rename or archive a thread; a change of status, summary or project needs the admin relation. |
updateConversationBranchSelection | Select which branch is the current path of a conversation after the user switches branches, so that later messages continue from the selected message; returns the ID of the selected message. |
updateConversationMessage | Replace the parts of an existing message to edit it in place; to keep the original, create a branch instead. |
updateConversationReadState | Advance the read cursor of the caller to a message of the conversation when the user has seen messages; the cursor never moves backwards. |
updateSchedule | Change the fields of a schedule, or pause and resume it with the status, where an omitted field keeps its value; returns the updated schedule. |
updateWebhook | Change the name, target, prompt template, event filter or status of a webhook, for example to enable or disable deliveries; returns the updated webhook. |