For AI agents: a documentation index is available at the root level at /llms.txt and /llms-full.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.
GuidesAPI Reference
GuidesAPI Reference
  • Overview
    • API reference
  • Search
    • POSTSearch
    • GETSearch Run List
    • GETSearch Run Get
    • GETSearch Run Events
    • POSTSearch Run Cancel
  • Extract
    • GETExtract a URL
    • POSTExtract
  • Monitors
    • GETList monitors
    • POSTCreate monitor
    • GETRetrieve monitor
    • DELDelete monitor
    • PATCHUpdate monitor
    • GETList monitor events
    • POSTMonitor Pause
    • POSTMonitor Resume
    • POSTRun monitor
  • Tasks
    • POSTTask
    • POSTCreate task run
    • GETRetrieve task run
    • GETStream task run events
    • GETTask List
    • GETTask Get
    • GETTask Events
    • POSTTask Cancel
  • Chat
    • POSTChat completion
  • Find All
    • POSTFindAll
    • GETFindall Run List
    • POSTCreate FindAll run
    • GETRetrieve FindAll run
    • GETStream FindAll run events
    • POSTCancel FindAll run
    • POSTExtend FindAll run
    • POSTEnrich FindAll run
LogoLogo
Tasks

Create task run

Deprecated
||View as Markdown|
POST
https://core.usescout.sh/v1/tasks/runs
POST
/v1/tasks/runs
$curl -X POST https://core.usescout.sh/v1/tasks/runs \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "task": "Find Anthropic'\''s CEO and headquarters city.",
>  "webhook": "https://hooks.usescout.sh/tasks/completed"
>}'
1{
2  "task_id": "task-4f7a2b9c8d1e4f3a9b7c",
3  "run_id": "run-9c4f1a7be2d04e3a8f56",
4  "status": "queued",
5  "task": "Find Anthropic's CEO and headquarters city.",
6  "query": "Find Anthropic's CEO and headquarters city.",
7  "credits": 5,
8  "createdAt": "2025-01-20T14:03:11+00:00"
9}

DEPRECATED — alias of POST /v1/task. Use that endpoint instead; this route remains only for back-compat.

Was this page helpful?
Previous

Task

Next

Retrieve task run

Built with

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

Allowed values:
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