Create Agent Run
Start an agent run. The run executes asynchronously: the response returns immediately with status queued, then poll GET .../runs/{run_id} until completed and fetch the output from GET .../runs/{run_id}/result — or set enable_events: true and follow GET .../runs/{run_id}/events for live progress.
To enrich existing records instead of researching from scratch, pass them in input_data; this requires an output_schema (on the request or the agent).
Authorization
BearerAuth In: header
Path Parameters
Web Search Agent ID, format wsa_<uuid>.
uuidRequest Body
application/json
Stable agent name. On this no-agent-id route, an unseen name creates a new agent; an existing name reuses it. Ignored on the /{agent_id}/runs route.
Effort level overriding the agent default for this run.
Whether to stream run events when supported.
falseUser prompt or task instructions for the run.
Existing records to ENRICH: a list of partial rows, or a single object, mirroring output_schema's shape.
JSON Schema overriding the agent's default structured output for this run. Root must be an object with non-empty properties or an array of objects. Hard limits: nesting depth ≤ 5, ≤ 100 properties, ≤ 500 enum values, no unsupported keywords (format, pattern, min/max*, root anyOf, standalone null). Invalid schemas return 422.
Previous interaction identifier used to continue a conversation.
Skill override for this run. One-time only, except when this run creates a new agent via agent_name, in which case it becomes the new agent's stored skill.
Source guidance overriding the agent default.
Only settable when this run creates a new agent (via agent_name, or when no agent is resolved), in which case it becomes the new agent's stored use_case. For a run against an existing agent, this must match the agent's own use_case - passing the same value is accepted as a no-op, a different value is rejected.
Response Body
application/json
application/json
application/json
curl -X POST "https://example.com/v2/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/runs" \ -H "Content-Type: application/json" \ -d '{ "input": "string" }'{ "completed_at": "2019-08-24T14:15:22Z", "created_at": "2019-08-24T14:15:22Z", "effort": "low", "error": { "message": "string", "ref_id": "string" }, "id": "string", "interaction_id": "string", "is_active": true, "prompt": "string", "started_at": "2019-08-24T14:15:22Z", "status": "queued", "web_search_agent_id": "string"}