API reference · Agents
Start a hosted run
POST/v1/agents/{id}/runsAPI key
Hosted agent runs (lib/agent-runs.ts): the agent's definition runs a loop on the server, model call and tool calls, each step a job of its own. Every model call is a request by the agent's own key, billed to its wallet under its policy. The owner's key with the agents scope runs any of its agents; an agent's own key runs itself. Refused with 409 no_definition before a definition is stored, and with 429 too_many_active_runs past the agent's live runs. A 404 while hosted runs are off on the deployment.
Parameters
| Field | Type | What it is |
|---|---|---|
| id (path)required | string | The agent's id; self on an agent's own key. |
Request body
application/json, required
| Field | Type | What it is |
|---|---|---|
| inputrequired | string or array of object | The user's message, or a list of { role: user | assistant, content } ending in the user's. |
| instructions | string or null | Added to the definition's for this run only. |
| metadata | object or null | |
| limits | object | |
| limits. | integer or null | Model calls and tool batches, together. |
| limits. | integer or null | Wall clock from the run's creation. |
| limits. | integer or null | What the run's model and image calls may be billed, in micro USD. |
Example
{
"input": "Say hello in five words.",
"instructions": "string",
"metadata": {},
"limits": {
"max_steps": 0,
"max_wall_seconds": 0,
"max_cost_micros": 0
}
}Answer 201
Started.
| Field | Type | What it is |
|---|---|---|
| object | string | One of "agent.run". |
| id | string | |
| agent_id | integer | |
| status | string | One of "queued", "in_progress", "requires_action", "cancelling", "completed", "incomplete", "failed", "cancelled", "expired". |
| model | string | |
| created | integer | |
| started_at | integer or null | |
| completed_at | integer or null | |
| expires_at | integer | |
| steps | integer | |
| max_steps | integer | |
| max_wall_seconds | integer | |
| cost_micros | integer | |
| max_cost_micros | integer | |
| usage | object | |
| usage. | integer | |
| usage. | integer | |
| output_text | string or null | |
| required_action | object or null | |
| required_action. | string | One of "submit_tool_outputs". |
| required_action. | object | |
| required_action. | array of object | |
| required_action. | string | |
| required_action. | string | One of "function". |
| required_action. | object | |
| required_action. | integer or null | |
| last_error | object or null | |
| last_error. | string | |
| last_error. | string | |
| incomplete_details | object or null | |
| incomplete_details. | string | One of "max_steps", "max_wall_time", "max_cost". |
| metadata | object or null |
Errors
- 400OpenAI shaped error.
- 401OpenAI shaped error.
- 403OpenAI shaped error.
- 404OpenAI shaped error.
- 409OpenAI shaped error.
- 429OpenAI 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.