> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Escolhendo o Extrator de Dados

> Compare /agent, /extract e /scrape (modo JSON) para escolher a ferramenta ideal para extrair dados estruturados

Firecrawl oferece três abordagens para extrair dados estruturados de páginas da web. Cada uma atende a diferentes casos de uso, com distintos níveis de automação e controle.

<div id="quick-comparison">
  ## Comparação Rápida
</div>

| Recurso                | `/agent`                              | `/extract`                                            | `/scrape` (modo JSON)                         |
| ---------------------- | ------------------------------------- | ----------------------------------------------------- | --------------------------------------------- |
| **Status**             | Ativo                                 | Use `/agent` em seu lugar                             | Ativo                                         |
| **URL Obrigatória**    | Não (opcional)                        | Sim (curingas suportados)                             | Sim (URL única)                               |
| **Escopo**             | Descoberta em toda a web              | Múltiplas páginas/domínios                            | Página única                                  |
| **Descoberta de URL**  | Pesquisa autônoma na web              | Rastreia a partir das URLs fornecidas                 | Nenhuma                                       |
| **Processamento**      | Assíncrono                            | Assíncrono                                            | Síncrono                                      |
| **Schema Obrigatório** | Não (prompt ou schema)                | Não (prompt ou schema)                                | Não (prompt ou schema)                        |
| **Preços**             | Dinâmico (5 execuções gratuitas/dia)  | Baseado em tokens (1 crédito = 15 tokens)             | 5 créditos/página (1 base + 4 para modo JSON) |
| **Melhor Para**        | Pesquisa, descoberta, coleta complexa | Extração em várias páginas (quando você sabe as URLs) | Extração de uma única página conhecida        |

<div id="1-agent-endpoint">
  ## 1. Endpoint `/agent`
</div>

O endpoint `/agent` é o recurso mais avançado do Firecrawl — o sucessor de `/extract`. Ele usa agentes de IA para pesquisar, navegar e coletar dados de forma autônoma em toda a web.

<div id="key-characteristics">
  ### Características principais
</div>

* **URLs opcionais**: Basta descrever o que você precisa no `prompt`; o uso de URLs é totalmente opcional
* **Navegação autônoma**: O agente pesquisa e navega profundamente em sites para encontrar seus dados
* **Busca profunda na web**: Descobre autonomamente informações em diversos domínios e páginas
* **Processamento paralelo**: Processa múltiplas fontes simultaneamente para resultados mais rápidos
* **Modelos disponíveis**: `spark-1-mini` (padrão, 60% mais barato) e `spark-1-pro` (maior precisão)

<div id="example">
  ### Exemplo
</div>

<CodeGroup>
  ```python Python theme={null}
  from firecrawl import Firecrawl
  from pydantic import BaseModel, Field
  from typing import List, Optional

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

  class Founder(BaseModel):
      name: str = Field(description="Nome completo do fundador")
      role: Optional[str] = Field(None, description="Cargo ou posição")
      background: Optional[str] = Field(None, description="Formação profissional")

  class FoundersSchema(BaseModel):
      founders: List[Founder] = Field(description="List of founders")

  result = app.agent(
      prompt="Find the founders of Firecrawl",
      schema=FoundersSchema,
      model="spark-1-mini",
      max_credits=100
  )

  print(result.data)
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl';
  import { z } from 'zod';

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

  const result = await firecrawl.agent({
    prompt: "Find the founders of Firecrawl",
    schema: z.object({
      founders: z.array(z.object({
        name: z.string().describe("Full name of the founder"),
        role: z.string().describe("Role or position").optional(),
        background: z.string().describe("Professional background").optional()
      })).describe("List of founders")
    }),
    model: "spark-1-mini",
    maxCredits: 100
  });

  console.log(result.data);
  ```

  ```bash cURL theme={null}
  curl -X POST "https://api.firecrawl.dev/v2/agent" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "prompt": "Find the founders of Firecrawl",
      "model": "spark-1-mini",
      "maxCredits": 100,
      "schema": {
        "type": "object",
        "properties": {
          "founders": {
            "type": "array",
            "description": "List of founders",
            "items": {
              "type": "object",
              "properties": {
                "name": { "type": "string", "description": "Full name" },
                "role": { "type": "string", "description": "Role or position" },
                "background": { "type": "string", "description": "Histórico profissional" }
              },
              "required": ["name"]
            }
          }
        },
        "required": ["founders"]
      }
    }'
  ```
</CodeGroup>

<div id="best-use-case-autonomous-research-discovery">
  ### Melhor caso de uso: Pesquisa e descoberta autônomas
</div>

**Cenário**: Você precisa encontrar informações sobre startups de IA que captaram uma rodada de investimento Série A, incluindo seus fundadores e os valores investidos.

**Por que `/agent`**: Você não sabe quais sites contêm essas informações. O agent irá pesquisar de forma autônoma na web, navegar até fontes relevantes (Crunchbase, sites de notícias, páginas das empresas) e compilar os dados estruturados para você.

Para mais detalhes, consulte a [documentação do Agent](/pt-BR/features/agent).

***

<div id="2-extract-endpoint">
  ## 2. Endpoint `/extract`
</div>

<Note>
  **Use `/agent` em vez disso**: Recomendamos migrar para [`/agent`](/pt-BR/features/agent) — é mais rápido, mais confiável, não requer URLs e cobre todos os casos de uso de `/extract` e mais.
</Note>

O endpoint `/extract` coleta dados estruturados de URLs especificadas ou de domínios inteiros usando extração com LLMs.

<div id="key-characteristics">
  ### Características principais
</div>

* **URLs normalmente necessárias**: Forneça pelo menos uma URL (aceita curingas como `example.com/*`)
* **Rastreamento de domínio**: Pode rastrear e analisar todas as URLs descobertas em um domínio
* **Aprimoramento com busca na web**: `enableWebSearch` opcional para seguir links fora dos domínios especificados
* **Schema opcional**: Suporta JSON Schema rígido OU prompts em linguagem natural
* **Processamento assíncrono**: Retorna um ID de tarefa para verificação de status

<div id="the-url-limitation">
  ### A limitação de URLs
</div>

O desafio fundamental com `/extract` é que você normalmente precisa conhecer as URLs de antemão:

1. **Lacuna de descoberta**: para tarefas como "encontrar startups da YC W24", você não sabe quais URLs contêm os dados. Você precisaria de uma etapa de pesquisa separada antes de chamar `/extract`.
2. **Busca na web pouco prática**: embora `enableWebSearch` exista, ele é limitado a começar pelas URLs que você fornece — um fluxo de trabalho pouco prático para tarefas de descoberta.
3. **Por que `/agent` foi criado**: `/extract` é bom em extrair de locais conhecidos, mas menos eficaz em descobrir onde os dados estão.

<div id="example">
  ### Exemplo
</div>

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

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

  schema = {
      "type": "object",
      "properties": {"description": {"type": "string"}},
      "required": ["description"],
  }

  res = firecrawl.extract(
      urls=["https://docs.firecrawl.dev"],
      prompt="Extrair a descrição da página",
      schema=schema,
  )

  print(res.data["description"])
  ```

  ```js Node theme={null}
  import { Firecrawl } from 'firecrawl';

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

  const schema = {
    type: 'object',
    properties: {
      title: { type: 'string' }
    },
    required: ['title']
  };

  const res = await firecrawl.extract({
    urls: ['https://docs.firecrawl.dev'],
    prompt: 'Extract the page title',
    schema,
    scrapeOptions: { formats: [{ type: 'json', prompt: 'Extract', schema }] }
  });

  console.log(res.status || res.success, res.data);
  ```

  ```bash cURL theme={null}
  curl -s -X POST "https://api.firecrawl.dev/v2/extract" \
    -H "Authorization: Bearer $FIRECRAWL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "urls": ["https://docs.firecrawl.dev"],
      "prompt": "Extraia o título da página",
      "schema": {
        "type": "object",
        "properties": {"title": {"type": "string"}},
        "required": ["title"]
      },
      "scrapeOptions": {
        "formats": [{"type": "json", "prompt": "Extraia", "schema": {"type": "object"}}]
      }
    }'
  ```
</CodeGroup>

<div id="best-use-case-targeted-multi-page-extraction">
  ### Caso de uso ideal: extração direcionada em múltiplas páginas
</div>

**Cenário**: Você tem a URL da documentação de um concorrente e quer extrair todos os endpoints de API deles de `docs.competitor.com/*`.

**Por que `/extract` funcionou aqui**: Você conhecia exatamente o domínio. Mas, mesmo assim, `/agent` com URLs fornecidas normalmente oferece resultados melhores hoje.

Para mais detalhes, consulte a [documentação do Extract](/pt-BR/features/extract).

***

<div id="3-scrape-endpoint-with-json-mode">
  ## 3. Endpoint `/scrape` com modo JSON
</div>

O endpoint `/scrape` com modo JSON é a abordagem mais controlada — ele extrai dados estruturados de uma única URL conhecida usando um LLM para analisar o conteúdo da página no schema que você especificar.

<div id="key-characteristics">
  ### Características principais
</div>

* **Apenas uma URL**: Projetado para extrair dados de uma única página específica por vez
* **URL exata obrigatória**: Você deve conhecer a URL exata que contém os dados
* **Schema opcional**: Pode usar JSON Schema OU apenas um prompt (o LLM escolhe a estrutura)
* **Síncrono**: Retorna os dados imediatamente (sem necessidade de polling de jobs)
* **Formatos adicionais**: Pode combinar extração em JSON com markdown, HTML e capturas de tela em uma única requisição

<div id="example">
  ### Exemplo
</div>

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

  app = Firecrawl(
    # Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
    # api_key="fc-SUA-CHAVE-API",
  )

  class CompanyInfo(BaseModel):
      company_mission: str
      supports_sso: bool
      is_open_source: bool
      is_in_yc: bool

  result = app.scrape(
      'https://firecrawl.dev',
      formats=[{
        "type": "json",
        "schema": CompanyInfo.model_json_schema()
      }],
      only_main_content=False,
      timeout=120000
  )

  print(result)
  ```

  ```js Node theme={null}
  import { Firecrawl } from "firecrawl";
  import { z } from "zod";

  const app = new Firecrawl({
    // Nenhuma API key necessária para começar — adicione uma para limites de taxa mais altos:
    // apiKey: "fc-YOUR_API_KEY",
  });

  // Define schema to extract contents into
  const schema = z.object({
    company_mission: z.string(),
    supports_sso: z.boolean(),
    is_open_source: z.boolean(),
    is_in_yc: z.boolean()
  });

  const result = await app.scrape("https://firecrawl.dev", {
    formats: [{
      type: "json",
      schema: schema
    }],
  });

  console.log(result);
  ```

  ```bash cURL theme={null}
  # Nenhuma API key necessária para começar — adicione -H "Authorization: Bearer YOUR_API_KEY" para limites de taxa mais altos:
  curl -X POST https://api.firecrawl.dev/v2/scrape \
      -H 'Content-Type: application/json' \
      -d '{
        "url": "https://firecrawl.dev",
        "formats": [ {
          "type": "json",
          "schema": {
            "type": "object",
            "properties": {
              "company_mission": {
                        "type": "string"
              },
              "supports_sso": {
                        "type": "boolean"
              },
              "is_open_source": {
                        "type": "boolean"
              },
              "is_in_yc": {
                        "type": "boolean"
              }
            },
            "required": [
              "company_mission",
              "supports_sso",
              "is_open_source",
              "is_in_yc"
            ]
          }
        } ]
      }'
  ```
</CodeGroup>

<div id="best-use-case-single-page-precision-extraction">
  ### Melhor caso de uso: Extração de alta precisão em página única
</div>

**Cenário**: Você está criando uma ferramenta de monitoramento de preços e precisa extrair o preço, o status de estoque e os detalhes do produto de uma página de produto específica para a qual você já tem a URL.

**Por que usar `/scrape` com modo JSON**: Você sabe exatamente qual página contém os dados, precisa de uma extração precisa de uma única página e quer resultados síncronos sem a sobrecarga de gerenciar tarefas.

Para mais detalhes, consulte a [documentação do modo JSON](/pt-BR/features/llm-extract).

***

<div id="decision-guide">
  ## Guia de decisão
</div>

**Você conhece a(s) URL(s) exata(s) que contém seus dados?**

* **NÃO** → Use `/agent` (descoberta autônoma na web)
* **SIM**
  * **Página única?** → Use `/scrape` com modo JSON
  * **Múltiplas páginas?** → Use `/agent` com URLs (ou `/scrape` em lote)

<div id="recommendations-by-scenario">
  ### Recomendações por Cenário
</div>

| Cenário                                                               | Endpoint Recomendado                |
| --------------------------------------------------------------------- | ----------------------------------- |
| "Encontrar todas as startups de IA e seus financiamentos"             | `/agent`                            |
| "Extrair dados desta página de produto específica"                    | `/scrape` (modo JSON)               |
| "Obter todos os artigos do blog de competitor.com"                    | `/agent` com URL                    |
| "Monitorar preços em várias URLs conhecidas"                          | `/scrape` com processamento em lote |
| "Pesquisar empresas em um setor específico"                           | `/agent`                            |
| "Extrair informações de contato de 50 páginas de empresas conhecidas" | `/scrape` com processamento em lote |

***

<div id="pricing">
  ## Preços
</div>

| Endpoint              | Custo                                           | Observações                                                       |
| --------------------- | ----------------------------------------------- | ----------------------------------------------------------------- |
| `/scrape` (modo JSON) | 5 créditos/página (1 base + 4 para o modo JSON) | Fixo, previsível                                                  |
| `/extract`            | Cobrado por tokens (1 crédito = 15 tokens)      | Variável de acordo com o conteúdo                                 |
| `/agent`              | Dinâmico                                        | 5 execuções gratuitas por dia; varia de acordo com a complexidade |

<div id="example-find-the-founders-of-firecrawl">
  ### Exemplo: "Encontre os fundadores da Firecrawl"
</div>

| Endpoint   | Como funciona                                                   | Créditos usados              |
| ---------- | --------------------------------------------------------------- | ---------------------------- |
| `/scrape`  | Você encontra a URL manualmente e depois faz scrape de 1 página | \~1 crédito                  |
| `/extract` | Você fornece URL(s) e ele extrai dados estruturados             | Variável (baseado em tokens) |
| `/agent`   | Basta enviar o prompt — o agente encontra e extrai              | \~100–500 créditos           |

**Trade-off**: `/scrape` é o mais barato, mas exige que você saiba a URL. `/agent` custa mais, mas cuida da descoberta automaticamente.

Para preços detalhados, consulte [Firecrawl Pricing](https://firecrawl.dev/pricing).

***

<div id="migration-extract-agent">
  ## Migração: `/extract` → `/agent`
</div>

Se você estiver usando `/extract` atualmente, a migração é simples:

**Antes (extract):**

```python theme={null}
result = app.extract(
    urls=["https://example.com/*"],
    prompt="Extract product information",
    schema=schema
)
```

**Depois (agente):**

```python theme={null}
result = app.agent(
    urls=["https://example.com"],  # Opcional - pode omitir completamente
    prompt="Extrair informações de produtos de example.com",
    schema=schema,
    model="spark-1-mini"  # ou "spark-1-pro" para maior precisão
)
```

A principal vantagem é que, com `/agent`, você pode simplesmente descrever o que precisa, sem nem precisar informar URLs.

***

<div id="key-takeaways">
  ## Principais pontos
</div>

1. **Sabe a URL exata?** Use `/scrape` com modo JSON — é a opção mais barata (5 créditos/página), mais rápida (síncrona) e mais previsível.

2. **Precisa de pesquisa autônoma?** Use `/agent` — ele cuida da descoberta automaticamente, com 5 execuções grátis/dia e depois precificação dinâmica baseada na complexidade.

3. **Migrando de `/extract`** para `/agent` em novos projetos — `/agent` é o sucessor, com recursos mais avançados.

4. **Trade-off entre custo e conveniência**: `/scrape` é mais econômico quando você já conhece suas URLs; `/agent` custa mais, mas elimina a descoberta manual de URLs.

***

<div id="further-reading">
  ## Leituras adicionais
</div>

* [Documentação do Agent](/pt-BR/features/agent)
* [Modelos do Agent](/pt-BR/features/models)
* [Documentação do modo JSON](/pt-BR/features/llm-extract)
* [Documentação do Extract](/pt-BR/features/extract)
* [Raspagem em lote](/pt-BR/features/batch-scrape)