Escolhendo o Extrator de Dados

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.

Comparação Rápida

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

1. Endpoint `/agent`

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.

Características principais

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)

Exemplo

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)

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);

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"]
    }
  }'

Melhor caso de uso: Pesquisa e descoberta autônomas

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.

2. Endpoint `/extract`

Use /agent em vez disso: Recomendamos migrar para /agent — é mais rápido, mais confiável, não requer URLs e cobre todos os casos de uso de /extract e mais.

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

Características principais

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

A limitação de URLs

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

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.
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.
Por que /agent foi criado: /extract é bom em extrair de locais conhecidos, mas menos eficaz em descobrir onde os dados estão.

Exemplo

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"])

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);

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"}}]
    }
  }'

Caso de uso ideal: extração direcionada em múltiplas páginas

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.

3. Endpoint `/scrape` com modo JSON

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.

Características principais

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

Exemplo

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)

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);

# 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"
          ]
        }
      } ]
    }'

Melhor caso de uso: Extração de alta precisão em página única

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.

Guia de decisão

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)

Recomendações por Cenário

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

Preços

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

Exemplo: “Encontre os fundadores da Firecrawl”

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.

Migração: `/extract` → `/agent`

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

result = app.extract(
    urls=["https://example.com/*"],
    prompt="Extract product information",
    schema=schema
)

Depois (agente):

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.

Principais pontos

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.
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.
Migrando de /extract para /agent em novos projetos — /agent é o sucessor, com recursos mais avançados.
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.

​Comparação Rápida

​1. Endpoint /agent

​Características principais

​Exemplo

​Melhor caso de uso: Pesquisa e descoberta autônomas

​2. Endpoint /extract

​Características principais

​A limitação de URLs

​Exemplo

​Caso de uso ideal: extração direcionada em múltiplas páginas

​3. Endpoint /scrape com modo JSON

​Características principais

​Exemplo

​Melhor caso de uso: Extração de alta precisão em página única

​Guia de decisão

​Recomendações por Cenário

​Preços

​Exemplo: “Encontre os fundadores da Firecrawl”

​Migração: /extract → /agent

​Principais pontos

​Leituras adicionais

Comparação Rápida

1. Endpoint `/agent`

Características principais

Exemplo

Melhor caso de uso: Pesquisa e descoberta autônomas

2. Endpoint `/extract`

Características principais

A limitação de URLs

Exemplo

Caso de uso ideal: extração direcionada em múltiplas páginas

3. Endpoint `/scrape` com modo JSON

Características principais

Exemplo

Melhor caso de uso: Extração de alta precisão em página única

Guia de decisão

Recomendações por Cenário

Preços

Exemplo: “Encontre os fundadores da Firecrawl”

Migração: `/extract` → `/agent`

Principais pontos

Leituras adicionais