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.
| Tool | Description |
|---|---|
| List conversation runs | List conversation runs. |
| List project runs | List project runs. |
| List runs | List runs; bound runtimes need own project_id, trigger_type=["schedule"] and trigger_id. |
| Get run | Get run details: status, errors, target, timing, token usage and cost, by run UUID or public id. |
| Get run analytics | Return account run analytics. |
| Create run | Create a run. |
| Update run | Update a run. |
| Delete run | Delete a run. |
| Cancel run | Cancel a run. |
| Finalize run | Finalize a run. |
| Ensure child run | Create or recover the child run of a parent run tool call. |
| Fail run | Fail a run. |
| Pause run | Pause a run. |
| Resume run | Resume a run. |
| Succeed run | Succeed a run. |
Events
Append, read, summarize, and stream run events, and list the event types.
| Tool | Description |
|---|---|
| List run event types | List run event types. |
| List run events | Read run event details: errors, steps, model calls and tool results, paginated by canonical UUID. |
| Get run event | Read one recorded event by canonical run UUID and numeric event_id. |
| Get run event summary | Count run events by type and time bucket without event bodies or usage metrics. |
| Get run snapshot | Read a run replay snapshot by canonical UUID; use event readers for targeted failure analysis. |
| Append run events | Append run events. |
| Stream run events | Stream run events. |
Input requests
Create, find, cancel, and respond to the input requests a run waits for.
| Tool | Description |
|---|---|
| List conversation input requests | List conversation input requests. |
| List run input requests | List run input requests. |
| Get input request | Return an input request. |
| Create input request | Create an input request. |
| Respond to input request | Respond to input request. |
| Cancel input request | Cancel an input request. |
Children
List the child runs a run starts.
| Tool | Description |
|---|---|
| List child runs | List direct child runs by canonical parent UUID; follow page_info.next for further children. |
| List conversation child runs | List conversation child runs. |
Triggers
Start runs from schedules, webhooks, and evaluations, and list the runs they started.
| Tool | Description |
|---|---|
| List project webhook runs | List webhook runs. |
| List webhook events | 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. |
| Create scheduled run | Run a schedule now. |
| Run webhook | 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. |
| List evaluation run projections | List the runs of one eval, newest first by default, to follow their status or pick a run to inspect; returns one page of eval runs. |
| List evaluation runs | List evaluation runs. |
| Get evaluation run | Read one run of an eval to follow its status or read its result summary; returns the eval run. |
| Get evaluation run report | Read the report of a finished eval run to inspect every example and metric result; returns the report document, or a conflict while the report is not written yet. |
| Run evaluation | Start a run of an eval against its agent, reading the eval from the project or a preview branch and running it on the main branch, an environment or a preview branch; returns the new eval run, which finishes in the background. |
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.
| Tool | Description |
|---|---|
| Create run event token | Issue a short-lived credential that appends events to a direct child run. |
| Send run heartbeat | Renew the execution lease of the current run generation. |
Tools
| Tool | Description |
|---|---|
| List connected agents | 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. |
| List conversation message branches | 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. |
| List conversation messages | List the messages of a conversation in sequence order, including branches, to render or replay a thread; returns one page of messages, paged with the returned cursor until it is null. |
| List conversation participants | List the users and agents in a conversation with their roles and read cursors to show who is in a thread; returns every participant in one page. |
| List 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. |
| List 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. |
| List source schedules | 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. |
| List source webhooks | 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. |
| List 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. |
| Get 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. |
| Get conversation message | Get one message of a conversation to refresh a single message, for example after streaming finishes; returns the message. |
| Get conversation read state | 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. |
| Get schedule | Read one schedule by its ID to inspect its target, cron expression, runtime target, state and last failure; returns the schedule. |
| Get 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. |
| Create conversation | 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. |
| Create conversation message | 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. |
| Create conversation message branch | 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. |
| Create conversation participant | Add a user to a conversation as member or viewer to share a thread; the operation needs the admin relation. |
| Create schedule | 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. |
| Create webhook | 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. |
| Update agent push runtime service | Drain or resume a runtime service. |
| Update conversation | 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. |
| Update conversation branch selection | 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. |
| Update conversation message | Replace the parts of an existing message to edit it in place; to keep the original, create a branch instead. |
| Update conversation read state | Advance the read cursor of the caller to a message of the conversation when the user has seen messages; the cursor never moves backwards. |
| Update schedule | 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. |
| Update webhook | Change the name, target, prompt template, event filter or status of a webhook, for example to enable or disable deliveries; returns the updated webhook. |
| Delete conversation | 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. |
| Delete conversation message | Delete one message from a conversation only when the user asks to remove that message; the deletion needs editor access. |
| Delete conversation participant | Remove a user from a conversation to revoke the access of that participant to the thread; the operation needs the admin relation. |
| Delete schedule | Delete a schedule that is no longer needed so that it starts no more runs; returns the acknowledgement ok: true. |
| Delete webhook | Delete a webhook that is no longer needed so that its URL refuses future deliveries; returns ok true once the webhook is deleted. |
| Replay webhook event | 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. |