Sign in
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

Request body

agent_namestring nullable

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'low' | 'medium' | 'high' | 'x-high' | '5x-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.

origin'api'

Origin of public API runs. Public requests are always API-originated.

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.

skillstring nullable

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.

use_case'research' | 'enrichment' | 'dataset_building'

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' | '5x-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.

Changes

Changed in 3 of the 55 revisions of this API.16

  • 22c2a229114611See the full diff
    • ●

      added the new 5x-high enum value to the effort response property for the response status 202

      response-property-enum-value-added

    • ○

      added the new 5x-high enum value to the request property effort/anyOf[subschema #1: Effort]/

      request-property-enum-value-added

    This revision also has 104 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • 1217768ca4014See the full diff
    • ○

      added the new optional request property agent_name

      new-optional-request-property

    • ○

      added the new optional request property origin

      new-optional-request-property

    • ○

      added the new optional request property skill

      new-optional-request-property

    • ○

      added the new optional request property use_case

      new-optional-request-property

  • d4e4f170f4f41See the full diff
    • ○

      endpoint added

      endpoint-added

    This revision also has 36 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog