Sign in

Run an agent

Triggers a run of the agent immediately, regardless of its cadence or active flag. The run is created pending and executed asynchronously — poll GET /agents/{id}/runs/{run_id} for status, summary, and output files. Unlike the rest of the agent-management surface, this endpoint also accepts a run's session key, letting one agent kick off another (triggered_by: agent); those requests are refused with 422 when they would loop — the target agent already ran in the trigger chain — or chain more than 5 runs deep.

post/agents/{id}/runs

Path parameters

idstring required

The unique identifier of the agent

Response

Run created and queued

idstring uuid
scheduled_agent_idstring uuid

The agent this run belongs to

triggered_by'manual' | 'schedule' | 'resume' | 'drop' | 'api' | 'agent'

api for runs started through this API with an API key; agent for runs started by another agent's run using its session key

triggered_by_user_idstring nullable

The user who started a manual run; null for API-triggered runs

triggered_by_run_idstring nullable

For agent-triggered runs: the run whose agent started this one

agent_review_task_idstring nullable

For resume runs: the review task whose resolution this run executes

status'pending' | 'running' | 'completed' | 'failed' | 'cancelled'
started_atstring date-time nullable
completed_atstring date-time nullable
duration_msinteger nullable
error_messagestring nullable
summarystring nullable

The agent's markdown summary of what it did

modelstring nullable

The model this run executed on

total_input_tokensinteger nullable
total_output_tokensinteger nullable
deliveryobject nullable

The email delivery record for this run's output files, when delivery ran

transcriptobject[]

Full event transcript. Only included when fetching a single run

created_atstring date-time

Changes