Sign in

v1

latestOpenAPI 3.1.02026-07-2658119246.0 KB
Public API

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).

post/v2/agents/{agent_id}/runs

Path parameters

agent_idstring uuid required

Web Search Agent ID, format wsa_<uuid>.

Request body

effort'low' | 'medium' | 'high' | 'x-high' | 'max'

Canonical effort tier names for the research graph.

enable_eventsboolean

Whether to stream run events when supported.

inputstring required

User prompt or task instructions for the run.

output_schemaobject nullable

JSON schema overriding the agent's default structured output for this run.

previous_interaction_idstring nullable

Previous interaction identifier used to continue a conversation.

Example request

{
  "input": "Find the 10 fastest growing AI startups in Europe and their latest funding rounds.",
  "sources": {
    "allow": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ],
    "block": [
      {
        "domains": [
          "linkedin.com",
          "crunchbase.com"
        ],
        "title": "Professional networks"
      }
    ]
  }
}

Response

Successful Response

completed_atstring date-time nullable

When the run completed.

created_atstring date-time required

When the run was created.

effort'low' | 'medium' | 'high' | 'x-high' | 'max' required

Canonical effort tier names for the research graph.

idstring required

Run identifier, format "task_run_{uuid}".

interaction_idstring required

Interaction ID.

is_activeboolean required

True while status is 'queued' or 'running'.

promptstring nullable

Prompt submitted for the run.

started_atstring date-time nullable

When the run started executing.

status'queued' | 'running' | 'completed' | 'failed' | 'cancelled' required

Lowercase status values used in API responses (distinct from the DB-level TaskRunStatus enum).

web_search_agent_idstring required

Web Search Agent instance this run belongs to.

Example response

{
  "id": "task_run_c0ffee00-0000-4000-8000-000000000000",
  "web_search_agent_id": "wsa_2af5b0e2-58b8-4b60-a1a4-9e57e4d33f00"
}