Runs & approvals
Starting and watching assistant runs, and answering what they ask.
The run object
As returned by GET /runs, one element of the list. Every endpoint below that returns this resource returns exactly these fields.
| Name | Type | Description |
|---|---|---|
idrequired | string (uuid) | Run id |
assistant_idrequired | string (uuid) | The assistant running |
assistantrequired | object | null | The assistant, or null if it has since been deleted |
assistant.idrequired | string (uuid) | Assistant id |
assistant.namerequired | string | Assistant name |
assistant.colorrequired | string | null | Accent colour |
statusrequired | string (enum) | Where the run is in its lifecyclequeuedrunningwaiting_replywaiting_approvalwaiting_childrencompletedfailedcancelled |
goalrequired | string | What this run was asked to do |
triggerrequired | object | Where the run came from |
trigger.typerequired | string | One of manual, inbound_message, schedule, event, webhook or delegation |
trigger.trigger_idrequired | string (uuid) | null | The assistant trigger, when one fired it |
trigger.trigger_namerequired | string | null | That trigger name |
trigger.event_keyrequired | string | null | The event key, for an event trigger |
contact_idrequired | string (uuid) | null | The contact it concerns, if any |
conversation_idrequired | string (uuid) | null | The thread it may answer in, if any |
parent_run_idrequired | string (uuid) | null | Set when this is a sub-agent of another run |
root_run_idrequired | string (uuid) | null | The top of the delegation tree |
depthrequired | integer | 0 for a root run |
resultrequired | object | null | Present once the run has ended |
result.outcomerequired | string | null | How it ended, in one word |
result.summaryrequired | string | null | One line on what happened |
tick_countrequired | integer | Model turns this run has taken |
cost_usdrequired | number | Billed AI spend attributed to this run |
error_coderequired | string | null | Machine code when the run failed |
error_messagerequired | string | null | Operator-facing failure text |
started_atrequired | string (date-time) | When the run was created |
ended_atrequired | string (date-time) | null | When it reached a terminal status |
created_atrequired | string (date-time) | When the row was written |
Endpoints
8 endpoints, each on its own page with its parameters, responses, error codes and samples in curl, Node and Python.