Create Run
Creates a minimal persistent Web Search Agent and starts a run for it. The response includes web_search_agent_id for later agent and run queries.
Authorization
BearerAuth In: header
Request 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
curl -X POST "https://example.com/v2/agents/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"}Create Agent POST
Create a Web Search Agent. Either pass `template` to materialize a pre-built template (its fields, goals, sources, and suggested questions are copied), or define the agent from scratch with `display_name`, `goals`, `sources`, and an optional `output_schema` for structured results.
List Agent Templates GET
List the pre-built agent templates available to your account. Use a template's `template_name` with `POST /v2/agents` to create an agent instance from it.