> ## Documentation Index
> Fetch the complete documentation index at: https://student-213fb9fc.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Crawlear

> O Firecrawl pode percorrer recursivamente os subdomínios de uma URL e coletar o conteúdo

Firecrawl rastreia sites com eficiência para extrair dados completos, lidando com infraestrutura web complexa. O processo:

1. **Análise de URL:** Examina o sitemap e percorre o site para identificar links
2. **Navegação:** Segue links recursivamente para encontrar todas as subpáginas
3. **Extração:** Extrai o conteúdo de cada página, lidando com JS e limites de taxa
4. **Resultado:** Converte os dados em markdown limpo ou em formato estruturado

Isso garante uma coleta abrangente de dados a partir de qualquer URL inicial.

<Card title="Experimente no Playground" icon="play" href="https://www.firecrawl.dev/playground?endpoint=crawl">
  Teste o rastreamento no playground interativo — sem precisar escrever código.
</Card>

<div id="crawling">
  ## Rastreamento
</div>

<div id="crawl-endpoint">
  ### endpoint /crawl
</div>

Usado para rastrear uma URL e todas as subpáginas acessíveis. Isso cria um job de rastreamento e retorna um ID de job para acompanhar o status do rastreamento.

<Warning>
  Por padrão, o Crawl ignora sublinks de uma página se eles não forem filhos da
  URL fornecida. Assim, website.com/other-parent/blog-1 não será
  retornado se você rastrear website.com/blogs/. Se você quiser
  website.com/other-parent/blog-1, use o parâmetro `crawlEntireDomain`. Para
  rastrear subdomínios como blog.website.com ao rastrear website.com, use o
  parâmetro `allowSubdomains`.
</Warning>

<Info>
  Por padrão, o crawler inclui o sitemap do site para descobrir URLs (`sitemap: "include"`). Se você definir `sitemap: "skip"`, o crawler só encontrará páginas alcançáveis por links HTML a partir da URL raiz. Arquivos como PDFs ou páginas profundamente aninhadas que estejam listadas no sitemap, mas não sejam linkadas diretamente de nenhuma página HTML, serão ignoradas. Para máxima cobertura, mantenha a configuração padrão `sitemap: "include"`.
</Info>

<div id="installation">
  ### Instalação
</div>

<CodeGroup>
  ```python Python theme={null}
  # pip install firecrawl-py

  from firecrawl import Firecrawl

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

  ```js Node.js theme={null}
  # npm install @mendable/firecrawl-js

  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: "fc-SUA-CHAVE-API" });
  ```

  ```bash CLI theme={null}
  # Instale globalmente com npm
  npm install -g firecrawl

  # Autentique (configuração única)
  firecrawl login
  ```
</CodeGroup>

<div id="usage">
  ### Uso
</div>

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

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

  docs = firecrawl.crawl(url="https://docs.firecrawl.dev", limit=10)
  print(docs)
  ```

  ```js Node.js theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

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

  const docs = await firecrawl.crawl('https://docs.firecrawl.dev', { limit: 10 });
  console.log(docs);
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 10
    }'
  ```

  ```bash CLI theme={null}
  # Inicia um trabalho de crawl (retorna o ID do trabalho)
  firecrawl crawl https://firecrawl.dev

  # Aguarda a conclusão exibindo o progresso
  firecrawl crawl https://firecrawl.dev --wait --progress --limit 100
  ```
</CodeGroup>

<Info>
  Cada página rastreada consome 1 crédito. O `limit` padrão de rastreamento é 10.000 páginas — defina um `limit` menor para controlar o uso de créditos (por exemplo, `limit: 100`). São cobrados créditos adicionais para certas opções: modo JSON custa 4 créditos adicionais por página, proxy aprimorado custa 4 créditos adicionais por página, e análise de PDF custa 1 crédito por página de PDF.
</Info>

<div id="scrape-options-in-crawl">
  ### Opções de scrape no crawl
</div>

Todas as opções do endpoint Scrape estão disponíveis no Crawl via `scrapeOptions` (JS) / `scrape_options` (Python). Elas se aplicam a cada página que o crawler coleta: formatos, proxy, cache, ações, localização, tags etc. Veja a lista completa na [Referência da API de Scrape](https://docs.firecrawl.dev/api-reference/endpoint/scrape).

<CodeGroup>
  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({ apiKey: 'fc-YOUR_API_KEY' });

  // Crawl with scrape options
  const crawlResponse = await firecrawl.crawl('https://example.com', {
    limit: 100,
    scrapeOptions: {
      formats: [
        'markdown',
        {
          type: 'json',
          schema: { type: 'object', properties: { title: { type: 'string' } } },
        },
      ],
      proxy: 'auto',
      maxAge: 600000,
      onlyMainContent: true,
    },
  });
  ```

  ```python Python theme={null}
  from firecrawl import Firecrawl

  firecrawl = Firecrawl(api_key='fc-YOUR_API_KEY')

  # Crawl with scrape options
  response = firecrawl.crawl('https://example.com',
      limit=100,
      scrape_options={
          'formats': [
              'markdown',
              { 'type': 'json', 'schema': { 'type': 'object', 'properties': { 'title': { 'type': 'string' } } } }
          ],
          'proxy': 'auto',
          'max_age': 600000,
          'only_main_content': True
      }
  )
  ```
</CodeGroup>

<div id="api-response">
  ### Resposta da API
</div>

Se você estiver usando cURL ou o método starter, será retornado um `ID` para verificar o status do crawl.

<Note>
  Se você estiver usando o SDK, consulte os métodos abaixo para entender o comportamento de waiter vs starter.
</Note>

```json theme={null}
{
  "success": true,
  "id": "123-456-789",
  "url": "https://api.firecrawl.dev/v2/crawl/123-456-789"
}
```

<div id="check-crawl-job">
  ### Verificar Job de Rastreamento
</div>

Usado para verificar o status de um job de rastreamento e obter seu resultado.

<Note>
  Os resultados do job ficam disponíveis via API por 24 horas após a conclusão. Após esse período, você ainda pode ver o histórico e os resultados dos seus rastreamentos nos [activity logs](https://www.firecrawl.dev/app/logs).
</Note>

<Note>
  As páginas no array `data` dos resultados do rastreamento são páginas que o Firecrawl conseguiu extrair com sucesso — mesmo que o site de destino tenha retornado um erro HTTP como 404. O campo `metadata.statusCode` mostra o código de status HTTP retornado pelo site de destino. Para recuperar páginas que o próprio Firecrawl não conseguiu extrair (por exemplo, erros de rede, timeouts ou bloqueios por robots.txt), use o endpoint dedicado [Get Crawl Errors](/pt-BR/api-reference/endpoint/crawl-get-errors) (`GET /crawl/{id}/errors`).
</Note>

<CodeGroup>
  ```python Python theme={null}
  status = firecrawl.get_crawl_status("<crawl-id>")
  print(status)
  ```

  ```js Node theme={null}
  const status = await firecrawl.getCrawlStatus("<id-da-varredura>");
  console.log(status);
  ```

  ```bash cURL theme={null}
  # Após iniciar um crawl, consulte o status pelo jobId
  curl -s -X GET "https://api.firecrawl.dev/v2/crawl/<jobId>" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY"
  ```

  ```bash CLI theme={null}
  # Verificar o status do crawl usando o ID do job
  firecrawl crawl <job-id>
  ```
</CodeGroup>

<div id="response-handling">
  #### Tratamento de respostas
</div>

A resposta varia conforme o status da varredura.

Para respostas não concluídas ou grandes (acima de 10 MB), é fornecido um parâmetro de URL `next`. Você deve requisitar essa URL para obter os próximos 10 MB de dados. Se o parâmetro `next` estiver ausente, isso indica o fim dos dados da varredura.

O parâmetro skip define o número máximo de resultados retornados em cada bloco.

<Info>
  Os parâmetros skip e next são relevantes apenas ao acessar a API diretamente.
  Se você estiver usando o SDK, nós cuidamos disso para você e retornaremos
  todos os resultados de uma vez.
</Info>

<CodeGroup>
  ```json Raspagem theme={null}
  {
    "status": "em andamento",
    "total": 36,
    "completed": 10,
    "creditsUsed": 10,
    "expiresAt": "2024-00-00T00:00:00.000Z",
    "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=10",
    "data": [
      {
        "markdown": "[Página inicial da documentação do Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
        "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
        "metadata": {
          "title": "Crie um 'Chat com o site' usando Groq Llama 3 | Firecrawl",
          "language": "en",
          "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
          "description": "Aprenda a usar o Firecrawl, o Groq Llama 3 e o LangChain para criar um bot de 'chat com seu site'."
          "ogLocaleAlternate": [],
          "statusCode": 200
        }
      },
      ...
    ]
  }
  ```

  ```json Concluído theme={null}
  {
    "status": "concluída",
    "total": 36,
    "completed": 36,
    "creditsUsed": 36,
    "expiresAt": "2024-00-00T00:00:00.000Z",
    "next": "https://api.firecrawl.dev/v2/crawl/123-456-789?skip=26",
    "data": [
      {
        "markdown": "[Página inicial da documentação do Firecrawl![logotipo claro](https://mintlify.s3-us-west-1.amazonaws.com/firecrawl/logo/light.svg)!...",
        "html": "<!DOCTYPE html><html lang=\"en\" class=\"js-focus-visible lg:[--scroll-mt:9.5rem]\" data-js-focus-visible=\"\">...",
        "metadata": {
          "title": "Crie um 'chat com o site' usando Groq Llama 3 | Firecrawl",
          "language": "en",
          "sourceURL": "https://docs.firecrawl.dev/learn/rag-llama3",
          "description": "Aprenda a usar o Firecrawl, o Groq Llama 3 e o LangChain para criar um bot de 'chat com seu site'."
          "ogLocaleAlternate": [],
          "statusCode": 200
        }
      },
      ...
    ]
  }
  ```
</CodeGroup>

<div id="sdk-methods">
  ### Métodos do SDK
</div>

Existem duas maneiras de usar o SDK:

1. **Crawl e aguarde** (`crawl`):
   * Aguarda a conclusão do crawl e retorna a resposta completa
   * Faz a paginação automaticamente
   * Recomendado para a maioria dos casos de uso

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl
  from firecrawl.types import ScrapeOptions

  firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

  # Rastreie um site:
  crawl_status = firecrawl.crawl(
    'https://firecrawl.dev', 
    limit=100, 
    scrape_options=ScrapeOptions(formats=['markdown', 'html']),
    poll_interval=30
  )
  print(crawl_status)
  ```

  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

  const firecrawl = new Firecrawl({apiKey: "fc-SUA_CHAVE_DE_API"});

  const crawlResponse = await firecrawl.crawl('https://firecrawl.dev', {
    limit: 100,
    scrapeOptions: {
      formats: ['markdown', 'html'],
    }
  })

  console.log(crawlResponse)
  ```
</CodeGroup>

A resposta inclui o status do crawl e todos os dados extraídos:

<CodeGroup>
  ```bash Python theme={null}
  success=True
  status='concluída'
  completed=100
  total=100
  creditsUsed=100
  expiresAt=datetime.datetime(2025, 4, 23, 19, 21, 17, tzinfo=TzInfo(UTC))
  next=None
  data=[
    Document(
      markdown='[Dia 7 - Launch Week III. Dia de Integrações — 14 a 20 de abril](...',
      metadata={
        'title': '15 projetos de web scraping em Python: do básico ao avançado',
        ...
        'scrapeId': '97dcf796-c09b-43c9-b4f7-868a7a5af722',
        'sourceURL': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
        'url': 'https://www.firecrawl.dev/blog/python-web-scraping-projects',
        'statusCode': 200
      }
    ),
    ...
  ]
  ```

  ```json Node theme={null}
  {
    success: true,
    status: "completed",
    completed: 100,
    total: 100,
    creditsUsed: 100,
    expiresAt: "2025-04-23T19:28:45.000Z",
    data: [
      {
        markdown: "[Day 7 - Launch Week III.Integrations DayApril ...",
        html: `<!DOCTYPE html><html lang="en" class="light" style="color...`,
        metadata: [Object],
      },
      ...
    ]
  }
  ```
</CodeGroup>

2. **Inicie e depois verifique o status** (`startCrawl`/`start_crawl`):
   * Retorna imediatamente com um ID de crawl
   * Permite verificar o status manualmente
   * Útil para crawls de longa duração ou lógica de polling personalizada

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl

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

  job = firecrawl.start_crawl(url="https://docs.firecrawl.dev", limit=10)
  print(job)

  # Verifique o status do rastreamento
  status = firecrawl.get_crawl_status(job.id)
  print(status)
  ```

  ```js Node.js theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

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

  const { id } = await firecrawl.startCrawl('https://docs.firecrawl.dev', { limit: 10 });
  console.log(id);

  // Verifique o status do crawl
  const status = await firecrawl.getCrawlStatus(id);
  console.log(status);

  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.firecrawl.dev/v2/crawl" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 10
    }'
  ```

  ```bash CLI theme={null}
  # Iniciar crawl (assíncrono, retorna o ID do job imediatamente)
  firecrawl crawl https://firecrawl.dev --limit 100

  # Depois verificar o status
  firecrawl crawl <job-id>
  ```
</CodeGroup>

<div id="crawl-websocket">
  ## WebSocket de Crawl
</div>

O método do Firecrawl baseado em WebSocket, `Crawl URL and Watch`, permite extrair e monitorar dados em tempo real. Inicie um crawl a partir de uma URL e personalize-o com opções como limite de páginas, domínios permitidos e formatos de saída — ideal para necessidades de processamento de dados imediatas.

<CodeGroup>
  ```python Python theme={null}
  import asyncio
  from firecrawl import AsyncFirecrawl

  async def main():
      firecrawl = AsyncFirecrawl(api_key="fc-YOUR-API-KEY")

      # Inicia um crawl primeiro
      started = await firecrawl.start_crawl("https://firecrawl.dev", limit=5)

      # Monitora atualizações (snapshots) até status final
      async for snapshot in firecrawl.watcher(started.id, kind="crawl", poll_interval=2, timeout=120):
          if snapshot.status == "completed":
              print("CONCLUÍDO", snapshot.status)
              for doc in snapshot.data:
                  print("DOC", doc.metadata.source_url if doc.metadata else None)
          elif snapshot.status == "failed":
              print("ERRO", snapshot.status)
          else:
              print("STATUS", snapshot.status, snapshot.completed, "/", snapshot.total)

  asyncio.run(main())
  ```

  ```js Node theme={null}
  import Firecrawl from '@mendable/firecrawl-js';

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

  // Inicie um crawl e depois acompanhe
  const { id } = await firecrawl.startCrawl('https://mendable.ai', {
    excludePaths: ['blog/*'],
    limit: 5,
  });

  const watcher = firecrawl.watcher(id, { kind: 'crawl', pollInterval: 2, timeout: 120 });

  watcher.on('document', (doc) => {
    console.log('DOC', doc);
  });

  watcher.on('error', (err) => {
    console.error('ERR', err?.error || err);
  });

  watcher.on('done', (state) => {
    console.log('DONE', state.status);
  });

  // Comece a acompanhar (WS com fallback em HTTP)
  await watcher.start();
  ```
</CodeGroup>

<div id="crawl-webhook">
  ## Webhook de Rastreamento
</div>

Você pode configurar webhooks para receber notificações em tempo real conforme o rastreamento avança. Isso permite processar páginas à medida que são coletadas, em vez de esperar a conclusão de todo o rastreamento.

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/crawl \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer YOUR_API_KEY' \
    -d '{
      "url": "https://docs.firecrawl.dev",
      "limit": 100,
      "webhook": {
        "url": "https://your-domain.com/webhook",
        "metadata": {
          "any_key": "any_value"
        },
        "events": ["iniciado", "página", "concluído"]
      }
    }'
```

<div id="quick-reference">
  ### Referência rápida
</div>

**Tipos de eventos:**

* `crawl.started` - Quando o rastreamento começa
* `crawl.page` - Para cada página rastreada com sucesso
* `crawl.completed` - Quando o rastreamento termina
* `crawl.failed` - Se o rastreamento encontrar um erro

**Payload básico:**

```json theme={null}
{
  "success": true,
  "type": "crawl.page",
  "id": "crawl-job-id",
  "data": [...], // Dados da página para eventos 'page'
  "metadata": {}, // Your custom metadata
  "error": null
}
```

<div id="security-verifying-webhook-signatures">
  ### Segurança: Verificando Assinaturas de Webhook
</div>

Toda requisição de webhook do Firecrawl inclui um cabeçalho `X-Firecrawl-Signature` contendo uma assinatura HMAC-SHA256. **Sempre verifique essa assinatura** para garantir que o webhook é autêntico e não foi adulterado.

**Como funciona:**

1. Obtenha seu segredo de webhook na [aba Advanced](https://www.firecrawl.dev/app/settings?tab=advanced) das configurações da sua conta
2. Extraia a assinatura do cabeçalho `X-Firecrawl-Signature`
3. Calcule o HMAC-SHA256 do corpo bruto da requisição usando o seu segredo
4. Compare com o cabeçalho de assinatura usando uma função com proteção contra ataques de timing (tempo constante)

<Warning>
  Nunca processe um webhook sem verificar sua assinatura primeiro. O cabeçalho `X-Firecrawl-Signature` contém a assinatura no formato: `sha256=abc123def456...`
</Warning>

Para exemplos completos de implementação em JavaScript e Python, consulte a [documentação de segurança de webhooks](/pt-BR/webhooks/security).

<div id="full-documentation">
  ### Documentação completa
</div>

Para uma documentação completa sobre webhooks, incluindo payloads de eventos detalhados, estrutura do payload, configuração avançada e solução de problemas, consulte a [documentação de Webhooks](/pt-BR/webhooks/overview).