Skip to main content
POST
Run an agent

Authorizations

X-API-KEY
string
header
required

Path Parameters

id
string
required

The unique identifier of the agent

Response

Run created and queued

One execution of an agent. Unset fields (e.g. error_message on a successful run) are omitted from responses.

id
string<uuid>
scheduled_agent_id
string<uuid>

The agent this run belongs to

triggered_by
enum<string>

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

Available options:
manual,
schedule,
resume,
drop,
api,
agent
triggered_by_user_id
string | null

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

triggered_by_run_id
string | null

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

agent_review_task_id
string | null

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

status
enum<string>
Available options:
pending,
running,
completed,
failed,
cancelled
started_at
string<date-time> | null
completed_at
string<date-time> | null
duration_ms
integer | null
error_message
string | null
summary
string | null

The agent's markdown summary of what it did

model
string | null

The model this run executed on

total_input_tokens
integer | null
total_output_tokens
integer | null
output_files
object[]

Files the agent produced for the operator

dropped_files
object[]

For drop runs: the file(s) this run was triggered to process

delivery
object | null

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

transcript
object[]

Full event transcript. Only included when fetching a single run

created_at
string<date-time>