Skip to main content

Crawl

POST /crawl starts a BFS crawl from a seed URL. It discovers internal links recursively and extracts Markdown content from each page found.

Endpoint

Authentication

X-API-Key header required. See Authentication.

Parameters

string
required
Seed URL to start the crawl. SSRF guard applied to the seed and every discovered link.
integer
required
Maximum pages to crawl. Public API: 1–50. Playground: 1–10. Recommended value: 10. No default — omitting it returns 422.
integer
Optional crawl depth cap, null by default. Must be >= 0 when provided.
boolean
Allow the crawl to follow subdomains of the seed host. Default: false.
string
Optional RE2 regex used to filter discovered absolute URLs. Default: "". Maximum length: 512 characters.
boolean
Extract only the main content block. Default: true.
Keep links in the final Markdown. Default: true.
boolean
Keep images in the final Markdown. Default: true.
boolean
Keep frame references in the final Markdown. Default: false.
boolean
Deterministically replace or remove long data: URLs. Default: false.
boolean
Enable PDF parsing for discovered documents. Default: true.
boolean
OCR fallback for PDFs without useful text. Default: false. Requires parse_pdf=true.
integer
Post-load wait in milliseconds. Default: 0. Range: 030000. Must stay below timeout_ms.
boolean
Disable animations and transitions before the configured wait. Default: false.
integer
Total page timeout in milliseconds. Default: 60000. Range: 1000300000.
string[]
Normalized tags attached to billed usage records. Default: [].

Cost

1 credit per successful page. PDF parsing and OCR do not add a separate tariff. The ceiling remains max_pages × 1.
From 5 estimated credits, the Playground asks for user confirmation before starting. Failed pages (block, timeout) do not consume credits.

Asynchronous flow

  1. Send POST /crawl → receive 202 with job_id
  2. Poll via GET /jobs/{job_id} every 2s
  3. When status: "SUCCESS", results are in the results field
  4. Results can be partial. stopped_reason documents the terminal reason: frontier_empty, max_pages, timeout, insufficient_credits, or invalid_seed
  5. Individual items may also include a stable reason such as pdf_parse_disabled, pdf_ocr_timeout, or pdf_ocr_resource_limit

Example

Successful response (via polling)

Limits

Errors