API reference

API reference · Agents

List an agent's runs

GET/v1/agents/{id}/runsAPI key

Newest first; ?limit (100 at most) and ?after=<run id> for the next page. A 404 while hosted runs are off on the deployment.

Parameters

Path and query parameters
FieldTypeWhat it is
id (path)requiredstringThe agent's id; self on an agent's own key.
limit (query)integerAt most 100.
after (query)stringA run id: the runs older than it.

Answer 200

The runs.

Fields of the 200 answer
FieldTypeWhat it is
objectstringOne of "list".
dataarray of object
data[].objectstringOne of "agent.run".
data[].idstring
data[].agent_idinteger
data[].statusstringOne of "queued", "in_progress", "requires_action", "cancelling", "completed", "incomplete", "failed", "cancelled", "expired".
data[].modelstring
data[].createdinteger
data[].started_atinteger or null
data[].completed_atinteger or null
data[].expires_atinteger
data[].stepsinteger
data[].max_stepsinteger
data[].max_wall_secondsinteger
data[].cost_microsinteger
data[].max_cost_microsinteger
data[].usageobject
data[].usage.prompt_tokensinteger
data[].usage.completion_tokensinteger
data[].output_textstring or null
data[].required_actionobject or null
data[].required_action.typestringOne of "submit_tool_outputs".
data[].required_action.submit_tool_outputsobject
data[].required_action.submit_tool_outputs.tool_callsarray of object
data[].required_action.expires_atinteger or null
data[].last_errorobject or null
data[].last_error.codestring
data[].last_error.messagestring
data[].incomplete_detailsobject or null
data[].incomplete_details.reasonstringOne of "max_steps", "max_wall_time", "max_cost".
data[].metadataobject or null
has_moreboolean

Errors

  • 401OpenAI shaped error.
  • 403OpenAI shaped error.
  • 404OpenAI shaped error.

Every error answers in one shape, with its type, code and the field it names. The whole list is in the docs' Errors section.

Antimatter