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.
Authorizations
Path Parameters
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.
The agent this run belongs to
api for runs started through this API with an API key; agent for runs started by another agent's run using its session key
manual, schedule, resume, drop, api, agent The user who started a manual run; null for API-triggered runs
For agent-triggered runs: the run whose agent started this one
For resume runs: the review task whose resolution this run executes
pending, running, completed, failed, cancelled The agent's markdown summary of what it did
The model this run executed on
Files the agent produced for the operator
For drop runs: the file(s) this run was triggered to process
The email delivery record for this run's output files, when delivery ran
Full event transcript. Only included when fetching a single run