API reference

Crawl jobs

Create a crawl job and retrieve its status and progress.

POST /v1/crawl-jobs

Requires the account bearer token and an Idempotency-Key of 8-200 characters. The schema is strict; unsupported fields are rejected.

Field	Required	Behavior
prompt	Yes	Trimmed string, 1-4,000 characters.
targets	Yes	Nonempty array of unique supported target IDs.
runCount	No	Integer, minimum/default 1; deployed maximum is configurable.
options.country	No	Supported two-letter country code, normalized uppercase.
webhook.url	When webhook is present	Credential-free public HTTPS URL, maximum 2,048 characters.
webhook.secret	No	Trimmed string, 16-200 characters; otherwise generated and returned as webhookSigningSecret.

{
  "prompt": "What are the best CRM tools for a small team?",
  "targets": [
    "google",
    "chatgpt",
    "perplexity"
  ],
  "runCount": 1,
  "options": {
    "country": "US"
  }
}

Optional completion callback

{
  "prompt": "What are the best CRM tools for a small team?",
  "targets": [
    "google",
    "chatgpt",
    "perplexity"
  ],
  "runCount": 1,
  "options": {
    "country": "US"
  },
  "webhook": {
    "url": "https://your-app.example.com/hooks/nostimates"
  }
}

If you omit webhook.secret, securely retain webhookSigningSecret returned at creation. The callback contains completion metadata and the authenticated result URL, not the artifact. See Webhooks for verification and delivery handling.

{
  "accepted": true,
  "crawlJobId": "8a1d1ac4-1bf4-4f2b-9c9c-bda9d2356e72",
  "replayed": false,
  "status": "queued"
}

The same account, key, and validated request return the original job with replayed: true and its current status. Changing the request under that key returns 409. Reuse the exact submitted request when retrying.

GET /v1/crawl-jobs/{id}

Requires the owning account token and a UUID job ID. A missing or unowned job returns 404. Status does not contain the full result artifact.

{
  "id": "8a1d1ac4-1bf4-4f2b-9c9c-bda9d2356e72",
  "prompt": "What are the best CRM tools for a small team?",
  "targets": [
    "google",
    "chatgpt",
    "perplexity"
  ],
  "requestedAt": "2026-10-09T10:00:00.000Z",
  "status": "completed",
  "result": {
    "url": "/v1/crawl-jobs/8a1d1ac4-1bf4-4f2b-9c9c-bda9d2356e72/result"
  },
  "progress": {
    "completedRuns": 2,
    "failedRuns": 1,
    "runningRuns": 0,
    "totalRuns": 3
  }
}

Status	Meaning
queued	Awaiting processing or re-dispatch.
running	Processing is underway.
finalizing	Browser tasks are terminal; the artifact is being assembled.
completed	Artifact is available, even if some or all collections failed.
failed	Parent-level terminal failure.

Active jobs and repeat limits

An account can have five active jobs in queued, running, or finalizing states. A further new job returns 429. This is distinct from the deployed maximum runCount and is not a per-minute request quota. No guaranteed Retry-After header or fixed public request-rate allowance is documented.