> ## 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.

# Busca

> Pesquise na web e obtenha o conteúdo completo dos resultados

A API de busca do Firecrawl permite realizar pesquisas na web e, opcionalmente, fazer scraping dos resultados em uma única operação.

* Escolha formatos de saída específicos (markdown, HTML, links, screenshots)
* Pesquise na web com parâmetros personalizáveis (localização, etc.)
* Opcionalmente, recupere o conteúdo dos resultados em vários formatos
* Controle a quantidade de resultados e defina limites de tempo

Para mais detalhes, consulte a [Referência da API do endpoint /search](https://docs.firecrawl.dev/api-reference/endpoint/search).

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

<div id="performing-a-search-with-firecrawl">
  ## Fazendo uma pesquisa com o Firecrawl
</div>

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

Usado para realizar pesquisas na web e, opcionalmente, obter conteúdo dos resultados.

<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="basic-usage">
  ### Uso básico
</div>

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

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

  results = firecrawl.search(
      query="firecrawl",
      limit=3,
  )
  print(results)
  ```

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

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

  const results = await firecrawl.search('firecrawl', {
    limit: 3,
    scrapeOptions: { formats: ['markdown'] }
  });
  console.log(results);
  ```

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

  ```bash CLI theme={null}
  # Buscar na web
  firecrawl search "firecrawl web scraping" --limit 5 --pretty
  ```
</CodeGroup>

<div id="response">
  ### Resposta
</div>

Os SDKs retornarão o objeto de dados diretamente. O cURL retornará a carga completa.

```json JSON theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://www.firecrawl.dev/",
        "title": "Firecrawl - The Web Data API for AI",
        "description": "The web crawling, scraping, and search API for AI. Built for scale. Firecrawl delivers the entire internet to AI agents and builders.",
        "position": 1
      },
      {
        "url": "https://github.com/firecrawl/firecrawl",
        "title": "mendableai/firecrawl: Turn entire websites into LLM-ready ... - GitHub",
        "description": "Firecrawl is an API service that takes a URL, crawls it, and converts it into clean markdown or structured data.",
        "position": 2
      },
      ...
    ],
    "images": [
      {
        "title": "Quickstart | Firecrawl",
        "imageUrl": "https://mintlify.s3.us-west-1.amazonaws.com/firecrawl/logo/logo.png",
        "imageWidth": 5814,
        "imageHeight": 1200,
        "url": "https://docs.firecrawl.dev/",
        "position": 1
      },
      ...
    ],
    "news": [
      {
        "title": "Y Combinator startup Firecrawl is ready to pay $1M to hire three AI agents as employees",
        "url": "https://techcrunch.com/2025/05/17/y-combinator-startup-firecrawl-is-ready-to-pay-1m-to-hire-three-ai-agents-as-employees/",
        "snippet": "It's now placed three new ads on YC's job board for “AI agents only” and has set aside a $1 million budget total to make it happen.",
        "date": "3 months ago",
        "position": 1
      },
      ...
    ]
  }
}
```

<div id="search-result-types">
  ## Tipos de resultados de busca
</div>

Além dos resultados da web padrão, o Search oferece tipos de resultados especializados por meio do parâmetro `sources`:

* `web`: resultados da web padrão (padrão)
* `news`: resultados focados em notícias
* `images`: resultados de busca de imagens

Você pode solicitar várias fontes em uma única chamada (por exemplo, `sources: ["web", "news"]`). Quando fizer isso, o parâmetro `limit` é aplicado **por tipo de fonte** — assim, `limit: 5` com `sources: ["web", "news"]` retorna até 5 resultados da web e até 5 resultados de notícias (10 no total). Se você precisar de parâmetros diferentes por fonte (por exemplo, valores diferentes de `limit` ou `scrapeOptions` diferentes), faça chamadas separadas.

<div id="search-categories">
  ## Categorias de pesquisa
</div>

Filtre os resultados por categorias específicas usando o parâmetro `categories`:

* `github`: Pesquise em repositórios do GitHub, código, issues e documentação
* `research`: Pesquise em sites acadêmicos e de pesquisa (arXiv, Nature, IEEE, PubMed, etc.)
* `pdf`: Pesquise por PDFs

<div id="github-category-search">
  ### Pesquisa por categoria no GitHub
</div>

Pesquise especificamente em repositórios do GitHub:

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "web scraping em Python",
    "categories": ["github"],
    "limit": 10
  }'
```

<div id="research-category-search">
  ### Pesquisa por categoria de pesquisa
</div>

Pesquise sites acadêmicos e de pesquisa:

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "transformers em aprendizado de máquina",
    "categories": ["pesquisa"],
    "limit": 10
  }'
```

<div id="mixed-category-search">
  ### Pesquisa com categorias mistas
</div>

Combine várias categorias em uma única pesquisa:

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "redes neurais",
    "categories": ["github", "pesquisa"],
    "limit": 15
  }'
```

<div id="category-response-format">
  ### Formato de resposta de categoria
</div>

Cada resultado de pesquisa inclui um campo `category` indicando sua fonte:

```json theme={null}
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://github.com/example/neural-network",
        "title": "Implementação de Rede Neural",
        "description": "Uma implementação de redes neurais em PyTorch",
        "category": "github"
      },
      {
        "url": "https://arxiv.org/abs/2024.12345",
        "title": "Avanços na Arquitetura de Redes Neurais",
        "description": "Artigo científico sobre melhorias em redes neurais",
        "category": "research"
      }
    ]
  }
}
```

Exemplos:

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "openai",
    "sources": ["news"],
    "limit": 5
  }'
```

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-SUA_CHAVE_DE_API" \
  -d '{
    "query": "Júpiter",
    "sources": ["imagens"],
    "limit": 8
  }'
```

<div id="hd-image-search-with-size-filtering">
  ### Pesquisa de imagens em alta definição com filtro por tamanho
</div>

Use operadores de imagem para encontrar imagens em alta resolução:

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "pôr do sol imagesize:1920x1080",
    "sources": ["images"],
    "limit": 5
  }'
```

```bash cURL theme={null}
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-SUA_API_KEY" \
  -d '{
    "query": "papel de parede de montanha larger:2560x1440",
    "sources": ["images"],
    "limit": 8
  }'
```

**Resoluções HD comuns:**

* `imagesize:1920x1080` - Full HD (1080p)
* `imagesize:2560x1440` - QHD (1440p)
* `imagesize:3840x2160` - 4K UHD
* `larger:1920x1080` - HD ou superior
* `larger:2560x1440` - QHD ou superior

<div id="search-with-content-scraping">
  ## Busca com Coleta de Conteúdo
</div>

Pesquise e recupere conteúdo dos resultados de busca em uma única operação.

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

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

  # Pesquisar e fazer scraping de conteúdo
  results = firecrawl.search(
      "firecrawl web scraping",
      limit=3,
      scrape_options={
          "formats": ["markdown", "links"]
      }
  )
  ```

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

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

  const results = await firecrawl.search('firecrawl', {
    limit: 3,
    scrapeOptions: { formats: ['markdown'] }
  });
  console.log(results);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "firecrawl web scraping",
      "limit": 3,
      "scrapeOptions": {
        "formats": ["markdown", "links"]
      }
    }'
  ```

  ```bash CLI theme={null}
  # Buscar e raspar resultados
  firecrawl search "firecrawl" --scrape --scrape-formats markdown --limit 5 --pretty
  ```
</CodeGroup>

Todas as opções do endpoint /scrape são compatíveis neste endpoint de busca por meio do parâmetro `scrapeOptions`.

<div id="response-with-scraped-content">
  ### Resposta com conteúdo extraído
</div>

```json theme={null}
{
  "success": true,
  "data": [
    {
      "title": "Firecrawl - A API definitiva de web scraping",
      "description": "A Firecrawl é uma poderosa API de web scraping que transforma qualquer site em dados limpos e estruturados para IA e análise.",
      "url": "https://firecrawl.dev/",
      "markdown": "# Firecrawl\n\nA API definitiva de web scraping\n\n## Transforme qualquer site em dados limpos e estruturados\n\nA Firecrawl facilita a extração de dados de sites para aplicações de IA, pesquisa de mercado, agregação de conteúdo e muito mais...",
      "links": [
        "https://firecrawl.dev/pricing",
        "https://firecrawl.dev/docs",
        "https://firecrawl.dev/guides"
      ],
      "metadata": {
        "title": "Firecrawl - A API definitiva de web scraping",
        "description": "A Firecrawl é uma poderosa API de web scraping que transforma qualquer site em dados limpos e estruturados para IA e análise.",
        "sourceURL": "https://firecrawl.dev/",
        "statusCode": 200
      }
    }
  ]
}
```

<div id="advanced-search-options">
  ## Opções avançadas de busca
</div>

A API de busca do Firecrawl oferece diversos parâmetros para personalizar suas buscas:

<div id="location-customization">
  ### Personalização de localização
</div>

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

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

  # Pesquisa com configuração de localização (Alemanha)
  search_result = firecrawl.search(
      "ferramentas de web scraping",
      limit=5,
      location="Germany"
  )

  # Processar os resultados
  for result in search_result.data:
      print(f"Título: {result['title']}")
      print(f"URL: {result['url']}")
  ```

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

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

  // Pesquisa com configurações de localização (Alemanha)
  const results = await firecrawl.search('ferramentas de web scraping', {
    limit: 5,
    location: "Alemanha"
  });

  // Processar os resultados
  console.log(results);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "ferramentas de web scraping",
      "limit": 5,
      "location": "Alemanha"
    }'
  ```

  ```bash CLI theme={null}
  # Buscar com localização
  firecrawl search "local restaurants" --location "San Francisco,California,United States" --country US --pretty
  ```
</CodeGroup>

<div id="time-based-search">
  ### Busca por período
</div>

Use o parâmetro `tbs` para filtrar resultados por período. Observe que `tbs` se aplica apenas a resultados da fonte `web` — ele não filtra resultados de `news` ou `images`. Se você precisar de notícias com filtro de tempo, considere usar a fonte `web` com o operador `site:` para direcionar domínios de notícias específicos.

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

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

  results = firecrawl.search(
      query="firecrawl",
      limit=5,
      tbs="qdr:d",
  )
  print(len(results.get('web', [])))
  ```

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

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

  const results = await firecrawl.search('firecrawl', {
    limit: 5,
    tbs: 'qdr:d', // último dia
  });

  console.log(results.web);
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "técnicas mais recentes de web scraping",
      "limit": 5,
      "tbs": "qdr:w"
    }'
  ```

  ```bash CLI theme={null}
  # Busca com filtro de tempo (última semana)
  firecrawl search "firecrawl updates" --tbs qdr:w --limit 5 --pretty
  ```
</CodeGroup>

Valores comuns de `tbs`:

* `qdr:h` - Última hora
* `qdr:d` - Últimas 24 horas
* `qdr:w` - Última semana
* `qdr:m` - Último mês
* `qdr:y` - Último ano
* `sbd:1` - Ordenar por data (mais recentes primeiro)

Para um filtro temporal mais preciso, você pode especificar intervalos de datas exatos usando o formato de intervalo personalizado:

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

  # Inicialize o cliente com sua API key
  firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

  # Buscar resultados de dezembro de 2024
  search_result = firecrawl.search(
      "firecrawl updates",
      limit=10,
      tbs="cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
  )
  ```

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

  // Inicialize o cliente com sua API key
  const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

  // Buscar resultados de dezembro de 2024
  firecrawl.search("firecrawl updates", {
    limit: 10,
    tbs: "cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
  })
  .then(searchResult => {
    console.log(searchResult.data);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "firecrawl updates",
      "limit": 10,
      "tbs": "cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
    }'
  ```
</CodeGroup>

Você pode combinar `sbd:1` com filtros de tempo para obter resultados ordenados por data dentro de um intervalo de tempo. Por exemplo, `sbd:1,qdr:w` retorna resultados da última semana ordenados do mais recente para o mais antigo, e `sbd:1,cdr:1,cd_min:12/1/2024,cd_max:12/31/2024` retorna resultados de dezembro de 2024 ordenados por data.

<div id="custom-timeout">
  ### Tempo limite personalizado
</div>

Defina um tempo limite personalizado para operações de pesquisa:

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

  # Inicialize o cliente com sua chave de API
  app = FirecrawlApp(api_key="fc-YOUR_API_KEY")

  # Defina um tempo limite de 30 segundos
  search_result = app.search(
      "complex search query",
      limit=10,
      timeout=30000  # 30 segundos em milissegundos
  )
  ```

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

  // Inicialize o cliente com sua chave de API
  const app = new FirecrawlApp({apiKey: "fc-YOUR_API_KEY"});

  // Defina um tempo limite de 30 segundos
  app.search("complex search query", {
    limit: 10,
    timeout: 30000  // 30 segundos em milissegundos
  })
  .then(searchResult => {
    // Processar os resultados
    console.log(searchResult.data);
  });
  ```

  ```bash cURL theme={null}
  curl -X POST https://api.firecrawl.dev/v2/search \
    -H "Content-Type: application/json" \
    -H "Authorization: Bearer fc-YOUR_API_KEY" \
    -d '{
      "query": "complex search query",
      "limit": 10,
      "timeout": 30000
    }'
  ```
</CodeGroup>

<div id="cost-implications">
  ## Implicações de custos
</div>

O custo de uma pesquisa é de 2 créditos por 10 resultados de pesquisa. Se as opções de scraping estiverem ativadas, os custos padrão de scraping se aplicam a cada resultado de pesquisa:

* **Basic scrape**: 1 crédito por página da web
* **PDF parsing**: 1 crédito por página de PDF
* **Enhanced proxy mode**: 4 créditos adicionais por página da web
* **JSON mode**: 4 créditos adicionais por página da web

Para ajudar a controlar os custos:

* Defina `parsers: []` se a análise de PDF não for necessária
* Use `proxy: "basic"` em vez de `"enhanced"` quando possível, ou defina como `"auto"`
* Limite o número de resultados de pesquisa com o parâmetro `limit`

<div id="advanced-scraping-options">
  ## Opções avançadas de scraping
</div>

Para mais detalhes sobre as opções de scraping, consulte a [documentação do recurso Scrape](https://docs.firecrawl.dev/features/scrape). Tudo, exceto o FIRE-1 (Agente) e o recurso rastreioDeMudanças, é compatível com este endpoint de Search.