FindAll | Scout | Documentation

curl -X POST https://core.usescout.sh/v1/findall \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "query": "S-1 stage AI infrastructure companies",
  "fields": [
    "name",
    "website",
    "headquarters"
  ],
  "limit": 20
}'

{
  "query": "S-1 stage AI infrastructure companies",
  "entities": [
    {
      "name": "CoreWeave",
      "website": "https://coreweave.com",
      "headquarters": "Livingston, New Jersey",
      "source": "https://en.wikipedia.org/wiki/CoreWeave"
    },
    {
      "name": "Lambda",
      "website": "https://lambdalabs.com",
      "headquarters": "San Francisco, California",
      "source": "https://lambdalabs.com/about"
    }
  ],
  "count": 2,
  "turns": 7,
  "credits": 7,
  "sources": [
    "https://en.wikipedia.org/wiki/CoreWeave",
    "https://lambdalabs.com/about"
  ]
}

Fast preview: enumerate candidate entities from a single SERP pass (no agent loop, no per-row enrichment). For comprehensive enumeration with reasoning + citations, use POST /v1/findall/runs.

Returns the Parallel-style FindAll shape — findall_id, metadata, status, candidates with output[<condition>] and basis — plus a flat entities/count/sources back-compat layer.

Fast preview: enumerate candidate entities from a single SERP pass (no agent loop, no per-row enrichment). For comprehensive enumeration with reasoning + citations, use POST /v1/findall/runs. Returns the Parallel-style FindAll shape — findall_id, metadata, status, candidates with output[<condition>] and basis — plus a flat `entities`/`count`/`sources` back-compat layer.

Authentication

AuthorizationBearer

Your API key, sent as a Bearer token.

Request

This endpoint expects an object.

querystringRequired>=1 character

Description of the entity set to enumerate.

fieldslist of strings or nullOptional

Column names for each entity row.

output_schemamap from strings to any or nullOptional

Optional JSON Schema each entity object must conform to. Takes precedence over fields for typed rows.

limitintegerOptional1-100Defaults to 20

Max entities to return.

Response

Successful Response

querystring

The enumeration query.

entitieslist of maps from strings to any

Matched entities as flat rows (back-compat).

countinteger

Number of entities returned.

turnsinteger

Agent steps taken.

creditsinteger

Cost of the call.

findall_idstring or null

Opaque identifier for this enumeration.

metadatamap from strings to any or null

Run metadata: {title, input} summarizing the query.

statusmap from strings to any or null

Run status: {status, is_active, metrics:{generated_candidates_count, matched_candidates_count}, termination_reason}.

candidateslist of maps from strings to any or null

Rich candidates: each with candidate_id, name, url, description, match_status, output{<field>:{type,value,is_matched}}, basis[{field,citations,reasoning,confidence}].

findall_schemamap from strings to any or null

Schema spec: {objective, entity_type, match_conditions:[{name,description}], generator, match_limit}.

sourceslist of strings

URLs retrieved during enumeration.

is_previewbooleanDefaults to false

True for the sync preview path (single SERP + one extraction pass). False from POST /v1/findall/runs.

Errors

422

Unprocessable Entity Error