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.

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'

api for runs started through this API

triggered_by_user_idstring nullable

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

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