Execution API

Start and monitor agent, task, and workflow runs. Find every run operation under Runs: lifecycle, events, input requests, children, and the runs that triggers start. Configure schedules and webhooks to trigger runs automatically. Runs · Conversations · Conversation Messages · Conversation Branches · Conversation Participants · Conversation Read State · Participant lookup · Project schedules · Project webhooks

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.

Endpoint	Methods	Description
`/runs`	POST	Create run
`/runs/{run_id}`	GET	Get run
`/runs/{run_id}/artifacts/{artifact_id}`	GET	Download a run artifact
`/runs/{run_id}/cancel`	POST	Cancel run
`/runs/{run_id}/pause`	POST	Pause run
`/runs/{run_id}/resume`	POST	Resume waiting run
`/projects/{project_reference}/runs`	GET	List project runs
`/conversations/{conversation_id}/runs`	GET	List conversation runs
`/conversations/{conversation_id}/runs/active`	GET	Get active conversation run
`/conversations/{conversation_id}/runs/{run_id}`	GET	Get conversation run
`/account/analytics/runs`	GET	Get account run analytics

Events

Read, summarize, and stream run events, and list the event types.

Endpoint	Methods	Description
`/runs/{run_id}/events`	GET	List run events
`/runs/{run_id}/events/{event_id}`	GET	Get run event
`/runs/{run_id}/events/summary`	GET	Summarize run events
`/runs/{run_id}/snapshot`	GET	Get run snapshot
`/runs/{run_id}/stream`	GET	Stream run events
`/runs/event-types`	GET	List run event types
`/schemas/run-events/{schema_file}`	GET	Get run event data schema
`/conversations/{conversation_id}/runs/{run_id}/events`	GET	List conversation run events
`/conversations/{conversation_id}/runs/{run_id}/snapshot`	GET	Get conversation run snapshot
`/conversations/{conversation_id}/runs/{run_id}/stream`	GET	Stream conversation run events

Input requests

Create, find, cancel, and respond to the input requests a run waits for.

Endpoint	Methods	Description
`/runs/{run_id}/input-requests`	GET, POST	List run input requests; Create run input request
`/runs/{run_id}/input-requests/{input_request_id}`	GET	Get run input request
`/runs/{run_id}/input-requests/{input_request_id}/responses`	POST	Respond to run input request
`/conversations/{conversation_id}/input-requests`	GET, POST	List conversation input requests; Create a conversation input request
`/conversations/{conversation_id}/input-requests/{input_request_id}`	GET	Get a conversation input request
`/conversations/{conversation_id}/input-requests/{input_request_id}/responses`	POST	Respond to a conversation input request
`/conversations/{conversation_id}/input-requests/{input_request_id}/cancel`	POST	Cancel a conversation input request

Children

List the child runs a run starts.

Endpoint	Methods	Description
`/runs/{run_id}/children`	GET	List child runs
`/conversations/{conversation_id}/runs/{run_id}/children`	GET	List conversation child runs
`/conversations/{conversation_id}/runs/children-by-parent-conversation`	GET	List child runs by parent conversation

Triggers

Start runs from schedules, webhooks, and evaluations, and list the runs they started.

Endpoint	Methods	Description
`/projects/{project_reference}/schedules/{schedule_id}/runs`	POST	Create scheduled run
`/projects/{project_reference}/webhooks/{webhook_definition_id}/runs`	GET	List project webhook runs
`/projects/{project_reference}/webhooks/{webhook_definition_id}/run`	POST	Run project webhook
`/projects/{project_reference}/evals/{eval_id}/runs`	GET, POST	List evaluation runs; Start an evaluation run
`/projects/{project_reference}/evals/{eval_id}/runs/{run_id}`	GET	Get evaluation run
`/projects/{project_reference}/evals/{eval_id}/runs/{run_id}/report`	GET	Get evaluation run report

Conversations

Create, read, update, or delete conversations. Find runs and input requests under Runs.

Endpoint	Methods	Description
`/conversations`	GET, POST	List conversations; Create conversation
`/conversations/{id}`	GET, PATCH, DELETE	Get conversation; Update conversation; Delete conversation
`/conversations/{id}/tree`	GET	Get conversation tree

Conversation Messages

List, send, read, edit, or delete messages.

Endpoint	Methods	Description
`/conversations/{id}/messages`	GET, POST	List messages; Send message
`/conversations/{conversation_id}/messages/{message_id}`	GET, PATCH, DELETE	Get message; Edit message; Delete message

Conversation Branches

Fork messages and select the active branch.

Endpoint	Methods	Description
`/conversations/{conversation_id}/branches`	POST	Fork message
`/conversations/{conversation_id}/branches/{message_id}`	GET	List message branches
`/conversations/{conversation_id}/branch-selection`	GET, PUT	Get branch selection; Update branch selection

Conversation Participants

List, add, or remove participants.

Endpoint	Methods	Description
`/conversations/{conversation_id}/participants`	GET, POST	List participants; Add participant
`/conversations/{conversation_id}/participants/{user_id}`	DELETE	Remove participant

Conversation Read State

Read or update conversation read state.

Endpoint	Methods	Description
`/conversations/{conversation_id}/read-state`	GET, PUT	Get read state; Update read state

Participant lookup

Find an existing participant identity by user or agent ID. Use the conversation participant endpoints to add or remove users.

Endpoint	Methods	Description
`/participants`	GET	List participant identities

Project schedules

Configure schedules. To start a run from an existing schedule, use POST /projects/{project_reference}/schedules/{schedule_id}/runs.

Endpoint	Methods	Description
`/projects/{project_reference}/schedules`	GET, POST	List project schedules; Create project schedule
`/projects/{project_reference}/schedules/{schedule_id}`	GET, PATCH, DELETE	Get project schedule; Update project schedule; Delete project schedule

Project webhooks

Configure automation webhooks and replay recorded deliveries. Start a webhook run and list its runs under Runs.

Endpoint	Methods	Description
`/projects/{project_reference}/webhooks`	GET, POST	List project webhooks; Create project webhook
`/projects/{project_reference}/webhooks/{webhook_definition_id}`	GET, PATCH, DELETE	Get project webhook; Update project webhook; Delete project webhook
`/projects/{project_reference}/webhooks/{webhook_definition_id}/events/{webhook_event_id}/replay`	POST	Replay project webhook event

Back to REST API reference

Get started

APIs

REST API

GraphQL API

MCP API

Runs

Lifecycle

Events

Input requests

Children

Triggers

Conversations

Conversation Messages

Conversation Branches

Conversation Participants

Conversation Read State

Participant lookup

Project schedules

Project webhooks

​Runs

​Lifecycle

​Events

​Input requests

​Children

​Triggers

​Conversations

​Conversation Messages

​Conversation Branches

​Conversation Participants

​Conversation Read State

​Participant lookup

​Project schedules

​Project webhooks

Runs

Lifecycle

Events

Input requests

Children

Triggers

Conversations

Conversation Messages

Conversation Branches

Conversation Participants

Conversation Read State

Participant lookup

Project schedules

Project webhooks