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
Find All

Create FindAll run

||View as Markdown|
POST
https://core.usescout.sh/v1/findall/runs
POST
/v1/findall/runs
$curl -X POST https://core.usescout.sh/v1/findall/runs \
>     -H "Authorization: Bearer <token>" \
>     -H "Content-Type: application/json" \
>     -d '{
>  "query": "S-1 stage AI infrastructure companies",
>  "fields": [
>    "name",
>    "website",
>    "headquarters"
>  ],
>  "limit": 20,
>  "webhook": "https://example.com/hooks/scout"
>}'
1{
2  "findall_id": "fa-37e97d4654d14fa6ad2fb342",
3  "status": null,
4  "query": "S-1 stage AI infrastructure companies",
5  "entities": [],
6  "count": 0,
7  "credits": 0,
8  "fields": [
9    "name",
10    "website",
11    "headquarters"
12  ],
13  "createdAt": "2025-01-20T14:10:02+00:00"
14}

Start an async entity-discovery run. Returns a findall_id at once; poll GET /v1/findall/runs/{id}, stream /events, or supply a webhook.

Was this page helpful?
Previous

Findall Run List

Next

Retrieve FindAll run

Built with

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 find.
webhookstring or nullOptional
If set, the finished run is POSTed here.

Response

Successful Response
findall_idstring
Opaque run identifier.
statusany

String for back-compat (queued/running/completed/failed/cancelled) OR the rich Parallel-style status object when the run has completed.

querystring
The enumeration query.
entitieslist of maps from strings to any

Entities found so far (flat rows; back-compat).

countinteger
Number of entities found.
creditsinteger
Cost accumulated by the run.
fieldslist of strings or null
The requested entity fields, if any.
output_schemamap from strings to any or null
The JSON Schema for entity objects, if any.
candidateslist of maps from strings to any or null
Rich candidates once the run has completed.
metadatamap from strings to any or null

Run metadata: {title, input}.

findall_schemamap from strings to any or null

Schema spec: objective, conditions, generator.

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

ISO-8601 created.

completedAtstring or null

ISO-8601 finished.

Errors

422
Unprocessable Entity Error