Sign in
Web Search Agents (public)

Create Run

Create a research run for a Web Search Agent instance.

post/v1/task-agents/{agent_id}/runs

Path parameters

agent_idstring uuid required

Request body

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.

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.

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 6 of the 55 revisions of this API.3724

  • 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

  • d4e4f170f4f4116See the full diff
    • ▲

      removed AgentSources from the sources request property anyOf list

      request-property-any-of-removed

    • ●

      removed the optional property workspace_id from the response with the 202 status

      response-optional-property-removed

    • ○

      api operation id create_run_api_v2_public_web_search_agents__agent_id__runs_post removed and replaced with create_run_public_v1_api_v1_public_web_search_agents__agent_id__runs_post

      api-operation-id-removed

    • ○

      endpoint deprecated

      endpoint-deprecated

    • ○

      added the new optional request property input_data

      new-optional-request-property

    • ○

      added AgentSourcesPublicV1 to the sources request property anyOf list

      request-property-any-of-added

    • ○

      added TaskRunErrorPublicV1 to the error response property anyOf list for the response status 202

      response-property-any-of-added

    • ○

      removed TaskRunError from the error response property anyOf list for the response status 202

      response-property-any-of-removed

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

  • e8a97dc9fce21515See the full diff
    • ▲

      for the path request parameter agent_id, the type/format was changed from string/ to string/uuid

      request-parameter-type-changed

    • ●

      deleted the cookie request parameter token

      request-parameter-removed

    • ●

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

      response-property-enum-value-added

    • ●

      added the new low enum value to the effort response property for the response status 202

      response-property-enum-value-added

    • ●

      added the new medium enum value to the effort response property for the response status 202

      response-property-enum-value-added

    • ●

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

      response-property-enum-value-added

    • ○

      api operation id create_run_v2_web_search_agents__agent_id__runs_post removed and replaced with create_run_api_v2_public_web_search_agents__agent_id__runs_post

      api-operation-id-removed

    • ○

      the endpoint scheme security APIKeyCookie was added to the API

      api-security-added

    • ○

      the endpoint scheme security HTTPBearer was added to the API

      api-security-added

    • ○

      api tag Web Search Agents (public) added

      api-tag-added

    • ○

      api tag Web Search Agents removed

      api-tag-removed

    • ○

      added the new optional request property effort

      new-optional-request-property

    • ○

      added the new optional request property previous_interaction_id

      new-optional-request-property

    • ○

      added TaskRunError to the error response property anyOf list for the response status 202

      response-property-any-of-added

    • ○

      removed AgentRunError from the error response property anyOf list for the response status 202

      response-property-any-of-removed

    • ○

      the response property web_search_agent_id became required for the status 202

      response-property-became-required

    • ○

      removed the pro enum value from the effort response property for the response status 202

      response-property-enum-value-removed

    • ○

      removed the quick enum value from the effort response property for the response status 202

      response-property-enum-value-removed

    • ○

      removed the quickest enum value from the effort response property for the response status 202

      response-property-enum-value-removed

    • ○

      removed the research enum value from the effort response property for the response status 202

      response-property-enum-value-removed

    • ○

      response property web_search_agent_id list-of-types was narrowed by removing types null from media type application/json of response 202

      response-property-list-of-types-narrowed

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

  • ebe52c375b711See the full diff
    • ▲

      the web_search_agent_id/anyOf[subschema #1]/ response's property type/format changed from string/uuid to string/ for status 202

      response-property-type-changed

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

  • 2562e655b8f21See the full diff
    • ○

      added the new optional request property sources

      new-optional-request-property

  • 421a9851d61b1See the full diff
    • ○

      endpoint added

      endpoint-added

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