Skip to main content

Crawl

O endpoint POST /crawl inicia um crawl BFS (busca em largura) a partir de uma URL semente. Ele descobre links internos recursivamente e extrai o conteúdo em Markdown de cada página encontrada.

Endpoint

Autenticação

Header X-API-Key obrigatório. Veja Autenticação.

Parâmetros

string
obrigatório
URL semente para iniciar o crawl. SSRF guard aplicado na seed e em cada link descoberto.
integer
obrigatório
Número máximo de páginas a rastrear. API pública: 1–50. Playground: 1–10. Valor recomendado: 10. Sem valor default — omitir resulta em erro 422.
integer
Limite opcional de profundidade do crawl, null por padrão. Quando fornecido, deve ser >= 0.
boolean
Permite seguir subdomínios do host semente. Padrão: false.
string
Regex RE2 opcional para filtrar URLs absolutas descobertas. Padrão: "". Tamanho máximo: 512 caracteres.
boolean
Extrai apenas o conteúdo principal. Padrão: true.
Mantém links no Markdown final. Padrão: true.
boolean
Mantém imagens no Markdown final. Padrão: true.
boolean
Mantém referências de frames no Markdown final. Padrão: false.
boolean
Remove ou substitui URLs data: longas de forma determinística. Padrão: false.
boolean
Habilita parsing de PDF para documentos descobertos. Padrão: true.
boolean
Fallback de OCR para PDFs sem texto útil. Padrão: false. Requer parse_pdf=true.
integer
Espera após o carregamento, em milissegundos. Padrão: 0. Faixa: 030000. Deve ser menor que timeout_ms.
boolean
Desativa animações e transições antes da espera configurada. Padrão: false.
integer
Timeout total por página, em milissegundos. Padrão: 60000. Faixa: 1000300000.
string[]
Tags normalizadas e gravadas nos usage records cobrados. Padrão: [].

Custo

1 crédito por página bem-sucedida. Parsing de PDF e OCR não adicionam tarifa separada. O teto continua max_pages × 1.
A partir de 5 créditos estimados, o Playground solicita confirmação do usuário antes de iniciar. Páginas com falha (bloqueio, timeout) não consomem créditos.

Fluxo assíncrono

  1. Envie POST /crawl → receba 202 com job_id
  2. Poll via GET /jobs/{job_id} a cada 2s
  3. Quando status: "SUCCESS", os resultados estão no campo results
  4. Os resultados podem ser parciais. stopped_reason documenta a razão terminal: frontier_empty, max_pages, timeout, insufficient_credits ou invalid_seed
  5. Itens individuais também podem trazer um reason estável, como pdf_parse_disabled, pdf_ocr_timeout ou pdf_ocr_resource_limit

Exemplo

Resposta de sucesso (via polling)

Limites

Erros