Parse

O Parse converte documentos em dados limpos e prontos para LLMs. Envie um arquivo para /parse — ou use /scrape em uma URL pública de documento — e receba markdown, conteúdo por página, blocos de layout tipados ou JSON estruturado.

Preserva o layout: títulos, parágrafos, tabelas e fórmulas organizados na ordem de leitura
Inclui documentos digitalizados: extração de texto nativo com OCR como alternativa para páginas que contêm apenas imagens
Estrutura fundamentada: blocos de layout tipados com caixas delimitadoras e links para intervalos de caracteres no markdown (PDFs)
Compatível com formatos comuns: PDF, Word, Excel, PowerPoint, OpenDocument, EPUB, CSV, HTML
Suporte a Zero Data Retention

Na dúvida entre o Parse e o Scrape? Este vídeo explica as diferenças:

Guia de início rápido

from firecrawl import Firecrawl

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse("./report.pdf")

print(doc.markdown)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const doc = await firecrawl.parse({
  data: fs.readFileSync("./report.pdf"),
  filename: "report.pdf",
});

console.log(doc.markdown);

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"formats":["markdown"]};type=application/json'

Tem uma URL pública de documento em vez de um arquivo? /scrape detecta o tipo de arquivo e faz o parsing da mesma forma — com as mesmas opções e o mesmo resultado: firecrawl.scrape("https://example.com/report.pdf").

Resposta

Os SDKs retornam diretamente o objeto de documento. O cURL retorna o payload JSON.

{
  "success": true,
  "data": {
    "markdown": "# Annual Report\n\n...",
    "metadata": {
      "title": "Annual Report",
      "numPages": 42,
      "totalPages": 42,
      "sourceFile": "report.pdf"
    }
  }
}

numPages é o número de páginas efetivamente analisadas; totalPages é a contagem real de páginas do documento. Os valores coincidem, a menos que maxPages tenha truncado o resultado — por exemplo, analisar um PDF de 100 páginas com maxPages: 10 retorna numPages: 10 e totalPages: 100, então totalPages > numPages indica que o resultado foi truncado. totalPages é omitido quando não é possível determinar a contagem de páginas.

Além do markdown do documento, três resultados abrangem os casos em que uma única string de markdown não é suficiente: markdown por página e blocos de layout para documentos PDF, e JSON estruturado para todos os formatos. E quando tudo o que você precisa é da atribuição de página dentro do próprio markdown, marcadores de página anotam as quebras de página no local.

Markdown por página (PDF)

Defina pages: true no parser de PDF, e o documento também inclui um array pages com o markdown físico de cada página — útil quando você precisa saber de qual página veio o conteúdo ou processar as páginas de forma independente. Sem custo adicional.

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "pages": True}]),
)

for page in doc.pages:
    print(page.page_number, page.markdown[:80])

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", pages: true }] },
);

for (const page of doc.pages) {
  console.log(page.pageNumber, page.markdown.slice(0, 80));
}

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","pages":true}]};type=application/json'

"pages": [
  { "pageNumber": 1, "markdown": "# Annual Report\n\n..." },
  { "pageNumber": 2, "markdown": "..." }
]

Marcadores de página (PDF)

Defina pageMarkers: true no parser de PDF, e as páginas no markdown do documento serão separadas por um marcador de comentário HTML que identifica a página física seguinte:

...fim da página 1

---

<!-- page 2 -->

início da página 2...

Não há um novo campo de resposta — os marcadores são inseridos no markdown, portanto qualquer pipeline subsequente que processa apenas uma string de markdown mantém a atribuição por página. Os comentários são invisíveis quando o markdown é renderizado e fáceis de separar (, com numeração iniciando em 1). Sem custo adicional.

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "page_markers": True}]),
)

print(doc.markdown)
# ...fim da página 1
#
# ---
#
# <!-- página 2 -->
#
# início da página 2...

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", pageMarkers: true }] },
);

console.log(doc.markdown);
// ...fim da página 1
//
// ---
//
// <!-- página 2 -->
//
// início da página 2...

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","pageMarkers":true}]};type=application/json'

Os marcadores aparecem apenas entre as páginas — não há marcador inicial para a página 1. A numeração pode pular uma página quando o parser mescla conteúdo em uma quebra de página (uma tabela ou frase que continua na página seguinte não deixa um limite para marcar). Use pages: true quando precisar de cada página física separadamente; as duas options podem ser combinadas.

Blocos de layout (PDF)

Defina blocks: true no parser de PDF, e o documento também passará a incluir um array blocks: para cada página, os blocos de layout tipados que o mecanismo de análise detectou, com geometria e origem. Este é o equivalente estruturado do markdown — use-o para fundamentação de citações, criar sobreposições de destaque ou auditar o conteúdo de um documento. Sem custo adicional.

Uma página de PDF analisada com caixas delimitadoras coloridas sobrepostas a cada bloco de layout detectado: título, texto, cabeçalhos de seção, tabela, figura, legenda, rodapé e número da página — Todos os blocos que o mecanismo detecta, tipados e posicionados — as mesmas regiões que se tornam o markdown.

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

doc = firecrawl.parse(
    "./report.pdf",
    options=ScrapeOptions(parsers=[{"type": "pdf", "blocks": True}]),
)

for page in doc.blocks:
    for block in page.items:
        print(page.page_number, block.type, block.bbox)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./report.pdf"), filename: "report.pdf" },
  { parsers: [{ type: "pdf", blocks: true }] },
);

for (const page of doc.blocks) {
  for (const block of page.items) {
    console.log(page.pageNumber, block.type, block.bbox);
  }
}

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./report.pdf' \
  -F 'options={"parsers":[{"type":"pdf","blocks":true}]};type=application/json'

"blocks": [
  {
    "pageNumber": 1,
    "width": 1700,
    "height": 2200,
    "status": "ok",
    "items": [
      {
        "id": "p1.b0",
        "type": "title",
        "label": "doc_title",
        "bbox": [0.118, 0.054, 0.882, 0.092],
        "content": "# Annual Report",
        "markdownSpan": [0, 15],
        "readingOrder": 0,
        "source": "native_text",
        "confidence": { "layout": 0.97, "ocr": null }
      }
    ]
  }
]

Campos do bloco

Campo	Descrição
`id`	Estável dentro de uma resposta: `p<page>.b<index in reading order>`.
`type`	Tipo de bloco: `title`, `section_header`, `text`, `table`, `formula`, `figure`, `caption`, `page_number`, `page_header`, `page_footer`. Novos tipos podem surgir ao longo do tempo.
`label`	Rótulo bruto do modelo de layout, repassado para compatibilidade futura.
`bbox`	`[x0, y0, x1, y1]` normalizado de 0 a 1 em relação à página. Multiplique por `width`/`height` para obter coordenadas em pixels. `null` quando a página não tiver dimensões conhecidas.
`content`	O fragmento Markdown para o qual este bloco contribuiu.
`markdownSpan`	Deslocamentos de caracteres `[start, end)` no `markdown` do documento que abrangem o fragmento deste bloco. `null` quando o pós-processamento reescreveu o fragmento.
`readingOrder`	Posição na ordem de leitura detectada.
`source`	Caminho do pipeline que produziu o bloco (por exemplo, `native_text`, `layout_ocr`, `tsr`, `formula_model`).
`confidence`	Pontuação de detecção de `layout` (0–1) e confiança do texto de `ocr` quando a fonte fornecer uma; `null` caso contrário — nunca um agregado inventado.

Fundamentação: de uma resposta à página

markdownSpan vincula cada bloco ao trecho exato do markdown que ele produziu. Isso torna a fundamentação de citações uma consulta, não uma inferência: encontre o texto citado no markdown, localize o bloco cujo intervalo abrange esse deslocamento e você terá o número da página e a caixa delimitadora — sem jamais precisar pedir coordenadas a um modelo de linguagem.

def ground(doc, quote: str):
    start = doc["markdown"].find(quote)
    for page in doc["blocks"]:
        for block in page["items"]:
            span = block["markdownSpan"]
            if span and span[0] <= start < span[1]:
                return page["pageNumber"], block["bbox"]

function ground(doc, quote) {
  const start = doc.markdown.indexOf(quote);
  for (const page of doc.blocks) {
    for (const block of page.items) {
      const span = block.markdownSpan;
      if (span && span[0] <= start && start < span[1]) {
        return { pageNumber: page.pageNumber, bbox: block.bbox };
      }
    }
  }
}

Resultado JSON estruturado

Passe um schema JSON ou um prompt para extrair dados estruturados diretamente do documento:

from firecrawl import Firecrawl
from firecrawl.v2.types import ScrapeOptions
from pydantic import BaseModel

firecrawl = Firecrawl(api_key="fc-YOUR-API-KEY")

class Invoice(BaseModel):
    vendor: str
    total: float

doc = firecrawl.parse(
    "./invoice.pdf",
    options=ScrapeOptions(formats=[{
        "type": "json",
        "schema": Invoice.model_json_schema(),
    }]),
)

print(doc.json)

import { Firecrawl } from "firecrawl";
import fs from "node:fs";
import { z } from "zod";

const firecrawl = new Firecrawl({ apiKey: "fc-YOUR-API-KEY" });

const schema = z.object({
  vendor: z.string(),
  total: z.number(),
});

const doc = await firecrawl.parse(
  { data: fs.readFileSync("./invoice.pdf"), filename: "invoice.pdf" },
  { formats: [{ type: "json", schema }] },
);

console.log(doc.json);

curl -X POST https://api.firecrawl.dev/v2/parse \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -F 'file=@./invoice.pdf' \
  -F 'options={"formats":[{"type":"json","schema":{"type":"object","properties":{"total":{"type":"number"},"vendor":{"type":"string"}}}}]};type=application/json'

Opções de PDF

Todo o comportamento relacionado a PDFs é controlado pela opção parsers, tanto em /parse quanto em /scrape:

{
  "parsers": [
    {
      "type": "pdf",
      "mode": "auto",
      "maxPages": 100,
      "pages": true,
      "blocks": true,
      "pageMarkers": true
    }
  ]
}

Propriedade	Tipo	Padrão	Descrição
`type`	`"pdf"`	(obrigatório)	Tipo de parser.
`mode`	`"fast" \| "auto" \| "ocr"`	`"auto"`	Estratégia de análise — veja abaixo.
`maxPages`	`integer`	—	Limita o número de páginas a analisar.
`pages`	`boolean`	`false`	Também retorna Markdown por página. Sem custo adicional.
`blocks`	`boolean`	`false`	Também retorna blocos de layout com caixas delimitadoras. Sem custo adicional.
`pageMarkers`	`boolean`	`false`	Anota as quebras de página no Markdown do documento com marcadores `<!-- page N -->`. Sem custo adicional.

Passar parsers: [] ignora completamente a análise e retorna o PDF em base64 (1 crédito fixo).

Modos de análise

Modo	Descrição
`auto`	Primeiro tenta a extração rápida baseada em texto e recorre ao OCR quando necessário. Este é o padrão.
`fast`	Somente extração baseada em texto (texto incorporado). É a opção mais rápida, mas falha em páginas digitalizadas ou que contêm apenas imagens, em vez de retornar silenciosamente um resultado vazio.
`ocr`	Força o OCR em todas as páginas. Use para documentos digitalizados ou quando `auto` classificar uma página incorretamente.

Formatos compatíveis

Extensões compatíveis: .html, .htm, .xhtml, .pdf, .docx, .doc, .docm, .odt, .ods, .odp, .rtf, .xlsx, .xls, .xlsm, .xlsb, .pptx, .ppt, .pptm, .epub, .csv. Consulte análise de documentos para saber como cada formato é convertido.

Referência da requisição

A requisição é multipart/form-data, com uma parte file obrigatória e uma parte JSON options opcional. options aceita um subconjunto das opções de scraping:

formats: Array de formatos de resultado. O padrão é ["markdown"]. Compatíveis: markdown, html, rawHtml, links, images, summary e json (com um schema ou prompt).
onlyMainContent: Retorna apenas o conteúdo principal do documento. O padrão é true.
includeTags / excludeTags: Inclusão ou exclusão em nível de tag (entradas HTML).
redactPII: Redige informações de identificação pessoal do markdown retornado.
timeout: Tempo limite da requisição em milissegundos. O padrão é 30000, máximo de 300000.
parsers: Controles do parser de arquivos — consulte as opções de PDF.

/parse não oferece suporte a opções exclusivas do navegador, como actions, waitFor, location, mobile ou rastreamento de alterações.

Usando o Firecrawl via MCP? Use firecrawl_parse para arquivos locais. O MCP local pode ler o arquivo diretamente quando configurado com FIRECRAWL_API_URL. O MCP remoto hospedado primeiro retorna um comando de upload temporário e, em seguida, processa o uploadRef retornado. URLs públicas de documentos ainda devem usar /scrape.

Considerações

O tamanho máximo do arquivo é de 50 MB por requisição.
A análise de PDFs é cobrada a 1 crédito por página; as opções pages, blocks e pageMarkers não geram custo adicional.
A análise de PDFs muito grandes ou digitalizados no modo ocr pode demorar mais — aumente o valor de timeout ou use maxPages para limitar o processamento.
Para lotes de arquivos, chame /parse para cada arquivo em paralelo; não há opção de upload em lote.

É um agente de IA que precisa de uma chave de API do Firecrawl? Consulte firecrawl.dev/agent-onboarding/SKILL.md para ver instruções de onboarding automatizado.

Primeiros passos

Endpoints principais

Mais

Guias de início rápido

Guias para desenvolvedores

Webhooks

Casos de uso

Outros

Como contribuir

Guia de início rápido

Resposta

Markdown por página (PDF)

Marcadores de página (PDF)

Blocos de layout (PDF)

Campos do bloco

Fundamentação: de uma resposta à página

Resultado JSON estruturado

Opções de PDF

Modos de análise

Formatos compatíveis

Referência da requisição

Considerações

​Guia de início rápido

​Resposta

​Markdown por página (PDF)

​Marcadores de página (PDF)

​Blocos de layout (PDF)

​Campos do bloco

​Fundamentação: de uma resposta à página

​Resultado JSON estruturado

​Opções de PDF

​Modos de análise

​Formatos compatíveis

​Referência da requisição

​Considerações

Guia de início rápido

Resposta

Markdown por página (PDF)

Marcadores de página (PDF)

Blocos de layout (PDF)

Campos do bloco

Fundamentação: de uma resposta à página

Resultado JSON estruturado

Opções de PDF

Modos de análise

Formatos compatíveis

Referência da requisição

Considerações