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
Search

Search

||View as Markdown|
POST
https://core.usescout.sh/v1/search
POST
/v1/search
$curl -X POST https://core.usescout.sh/v1/search \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "queries": [
>    "climate tech startups 2025",
>    "carbon capture funding"
>  ],
>  "depth": "fast",
>  "limit": 10,
>  "country": "us",
>  "language": "en",
>  "freshness": "month"
>}'
Run one or more web searches; return merged, de-duplicated results. For `depth` in {instant, fast, auto} this is synchronous: the response is the full `SearchResponse`. For `depth='deep'` the response is HTTP 202 with a `SearchRunView` carrying a `search_id` - poll GET /v1/searches/{search_id}, stream events via SSE (/v1/searches/{search_id}/events) or WebSocket (/v1/searches/{search_id}/ws), or pass a `webhook` URL on the body to receive the finished run.
Was this page helpful?
Previous

API reference

Next

Search Run List

Built with

Run one or more web searches; return merged, de-duplicated results.

For depth in {instant, fast, auto} this is synchronous: the response is the full SearchResponse. For depth='deep' the response is HTTP 202 with a SearchRunView carrying a search_id - poll GET /v1/searches/{search_id}, stream events via SSE (/v1/searches/{search_id}/events) or WebSocket (/v1/searches/{search_id}/ws), or pass a webhook URL on the body to receive the finished run.

Authentication

AuthorizationBearer
Your API key, sent as a Bearer token.

Request

This endpoint expects an object.
querieslist of stringsRequired

Keyword search queries to run; their results are merged and de-duplicated. Provide 1-5.

objectivestring or nullOptional

Natural-language description of what the caller is looking for. When set, results are automatically re-ranked by their relevance to this objective using a fast LLM pass - off-topic rows are dropped. Also focuses excerpts when advanced_settings.contents.highlights/summary is requested.

depthenumOptionalDefaults to auto

‘instant’ (~200ms, top of page, no enrichment), ‘fast’ (~450ms, single SERP page), ‘auto’ (~1s, recommended), ‘deep’ (~4-18s, multi-page gather + merge).

Allowed values:
modeenum or nullOptional

Alias of depth (basic -> fast, advanced -> auto). If both are supplied, depth wins.

Allowed values:
categoryenum or nullOptional

Result category hint. One of: company, research_paper, news, personal_site, financial_report, people.

limitintegerOptional1-100Defaults to 10
Maximum merged results to return.
countrystringOptionalDefaults to us

Two-letter country code to localize results.

locationstring or nullOptional

Alias of country (Parallel-style). If both are supplied, country wins.

languagestringOptionalDefaults to en
UI language code.
freshnessenum or nullOptional

Restrict to recent results: hour, day, week, month or year.

Allowed values:
include_domainslist of strings or nullOptional
Only return results whose URL is on these domains.
exclude_domainslist of strings or nullOptional
Drop results whose URL is on these domains.
max_excerpt_charsinteger or nullOptional>=1
Cap on total excerpt characters across all results.
session_idstring or nullOptional

Optional caller-supplied session id. Echoed back; if absent a new one is generated.

client_modelstring or nullOptional

Caller’s model identifier. Echoed only; not used.

advanced_settingsobject or nullOptional

Envelope for advanced tuning - source policy (include/exclude domains, date window), excerpt sizing, and inline second-pass content extraction.

webhookstring or nullOptional

If set, deep-mode (depth='deep') runs POST the finished payload to this URL. Ignored for non-deep depths (which return synchronously).

promptstring or nullOptional

Research question for the agentic deep-research engine (only applied when depth='deep'). When absent, the engine falls back to joining queries.

max_subqueriesinteger or nullOptional1-12

Caps the planner’s sub-query count (deep only). Default 8.

max_fetchesinteger or nullOptional1-30

Global cap on pages fetched across all sub-queries (deep only). Default 18.

Response

Successful Response

Errors

422
Unprocessable Entity Error