API ReferenceTasks

Task

View as Markdown
Start an async deep-research task. Returns a `task_id` immediately; poll GET /v1/tasks/{task_id}, stream events via SSE (/v1/tasks/{task_id}/events) or WebSocket (/v1/tasks/{task_id}/ws), or pass a `webhook` URL to receive the finished run. A `TaskRequest` (no `webhook`) is accepted for back-compat; the field is optional in the underlying model.

Authentication

AuthorizationBearer
Your API key, sent as a Bearer token.

Request

This endpoint expects an object.
taskstringRequired>=1 character

The natural-language objective.

output_schemaobject or map from strings to any or nullOptional

Output spec — either the new {type, json_schema?, description?} object, or a bare JSON Schema (legacy) which is treated as {type:‘json’, json_schema:{name:‘output’, schema:<arg>}}.

processorenumOptionalDefaults to core

Processor tier. base=haiku/no-thinking/≤3 tools, core=sonnet/adaptive/≤8 (default), ultra=opus/xhigh/≤15, research=agentic deep-research engine (planner + grader + per-finding + final synth).

max_subqueriesinteger or nullOptional1-12

Research tier only: caps the planner’s sub-query count. Default 8.

max_fetchesinteger or nullOptional1-30

Research tier only: global cap on pages fetched across all sub-queries. Default 18.

metadatamap from strings to strings or nullOptional

Free-form user metadata, echoed in webhooks/polls.

webhookstring or nullOptional

If set, the completed (or failed) run is POSTed here.

Response

Successful Response
task_idstring

Opaque task identifier (alias of run_id).

run_idstring

Opaque run identifier (alias of task_id).

statusstring
queued, running, completed, failed or cancelled.
taskstring
The objective.
querystring

The objective verbatim (alias of task).

creditsinteger
Cost accumulated by the run.
processorstringDefaults to core

Processor tier used: base | core | ultra.

metadatamap from strings to strings or null

Free-form user metadata, echoed back.

fieldslist of strings

Output field names, derived from output_schema.

output_schemamap from strings to any or null
The requested output spec, if any.
outputany

The answer once completed. For type=json, the parsed JSON object. For text/auto, the string. Null until completed.

basislist of objects

Per-field citation basis (empty until completed).

usageobject or null

Usage stats: tool_calls, search_queries, pages_fetched, tokens.

answerstringDefaults to

The agent’s answer text (empty until completed).

sourceslist of strings

Sample of source URLs the agent read (empty until done).

readlist of strings

Source URLs read in full (empty until completed).

consideredlist of strings

Source URLs considered (empty until completed).

errorstring or null
Failure reason when status is failed.
createdAtstring or null

ISO-8601 creation timestamp.

completedAtstring or null

ISO-8601 completion timestamp.

reportstring or null

Long-form markdown research report with inline [N] citations. Only present for research-tier runs.

findingslist of maps from strings to any or null

Per-sub_query findings ({subquery, answer, citations, confidence, evidence}). Research-tier only.

sources_detailedlist of maps from strings to any or null

Numbered sources list ({index, url, title, domain, fetched, quality, first_seen_subquery}). Research-tier only.

Errors

422
Unprocessable Entity Error