# Search

> Search the web and get full content from results

import InstallationPython from "/snippets/v2/installation/python.mdx";
import InstallationNode from "/snippets/v2/installation/js.mdx";
import InstallationCLI from "/snippets/v2/installation/cli.mdx";
import SearchPython from "/snippets/v2/search/base/python.mdx";
import SearchNode from "/snippets/v2/search/base/js.mdx";
import SearchCURL from "/snippets/v2/search/base/curl.mdx";
import SearchCLI from "/snippets/v2/search/base/cli.mdx";
import SearchContentPython from "/snippets/v2/search/content/python.mdx";
import SearchContentNode from "/snippets/v2/search/content/js.mdx";
import SearchContentCURL from "/snippets/v2/search/content/curl.mdx";
import SearchContentCLI from "/snippets/v2/search/content/cli.mdx";
import SearchLocationPython from "/snippets/v2/search/location/python.mdx";
import SearchLocationNode from "/snippets/v2/search/location/js.mdx";
import SearchLocationCURL from "/snippets/v2/search/location/curl.mdx";
import SearchLocationCLI from "/snippets/v2/search/location/cli.mdx";
import SearchTimePython from "/snippets/v2/search/time/python.mdx";
import SearchTimeNode from "/snippets/v2/search/time/js.mdx";
import SearchTimeCURL from "/snippets/v2/search/time/curl.mdx";
import SearchTimeCLI from "/snippets/v2/search/time/cli.mdx";
import SearchResponse from "/snippets/v2/search/base/output.mdx";
import PlaygroundCTA from "/snippets/shared/playground-cta-search.mdx";
import GovLegalFeedbackCTA from "/snippets/gov-legal-feedback-cta.mdx";

Search the web and get clean, structured content from every result in a single API call. Pass a query to `/search` and Firecrawl returns titles, descriptions, and URLs. Add `scrapeOptions` to also retrieve full-page markdown, HTML, links, or screenshots for each result.

Search results include query-relevant [Highlights](/features/search-highlights) by default. Set `highlights` to `false` when you want each website's plain description or snippet instead.

For the full parameter list, see the [Search Endpoint API Reference](https://docs.firecrawl.dev/api-reference/endpoint/search).

<PlaygroundCTA />

## Performing a Search with Firecrawl

### /search endpoint

Used to perform web searches and optionally retrieve content from the results.

### Installation 

<CodeGroup>
  <InstallationPython />
  <InstallationNode />
  <InstallationCLI />
</CodeGroup>

<GovLegalFeedbackCTA src="docs-search" />

### Basic Usage

<CodeGroup>

  <SearchPython />

  <SearchNode />

  <SearchCURL />

  <SearchCLI />

</CodeGroup>

### Response

SDKs will return the data object directly. cURL will return the complete payload.

<SearchResponse />

<Note>
**SDK users:** search results are grouped by source type, not under a generic `.data` array. Access web results with `result.web`, news with `result.news`, and images with `result.images`.

```python Python
result = firecrawl.search("query")
for item in result.web or []:
    print(item.url, item.title)
```

```js JavaScript
const result = await firecrawl.search("query");
for (const item of result.web ?? []) {
  console.log(item.url, item.title);
}
```
</Note>

## Search result types

In addition to regular web results, Search supports specialized result types via the `sources` parameter:

- `web`: standard web results (default)
- `news`: news-focused results
- `images`: image search results

You can request multiple sources in a single call (e.g., `sources: ["web", "news"]`). When you do, the `limit` parameter applies **per source type** — so `limit: 5` with `sources: ["web", "news"]` returns up to 5 web results and up to 5 news results (10 total). If you need different parameters per source (for example, different `limit` values or different `scrapeOptions`), make separate calls instead.

## Search Categories

Filter search results by specific categories using the `categories` parameter:

- `research`: Restrict web search to academic and research **websites** (arxiv.org, nature.com, ieee.org, pubmed.ncbi.nlm.nih.gov, biorxiv.org, medrxiv.org, and similar). Returns ordinary web page results with snippets — not paper records. To search papers themselves, use the [Research Index](/features/research)
- `pdf`: Search for PDFs
- `developer`: Search the [Developer Index](/features/developer) — issues, merged pull requests, and READMEs from public code repositories, alongside curated documentation sites

<Note>
**`research` is a website filter, not the paper index.** It narrows ordinary web search to a fixed list of academic domains and returns page snippets from them.

If you want to search scientific literature — full abstracts, in-paper passage reads, and citation-graph expansion over a paper index of PubMed, bioRxiv, medRxiv, and arXiv — use the [Research Index](/features/research) instead.
</Note>

### Research Category Search

Restrict web search to academic and research websites. This returns web pages hosted on those domains — landing pages, abstract pages, publisher pages — with the usual snippets:

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "machine learning transformers",
    "categories": ["research"],
    "limit": 10
  }'
```

To search the papers themselves rather than the websites that host them, use the [Research Index](/features/research), which searches paper abstracts across PubMed, bioRxiv, medRxiv, and arXiv and can read passages from inside a paper:

```bash cURL
curl -s "https://api.firecrawl.dev/v2/search/research/papers?query=CRISPR%20base%20editing%20off-target%20effects&k=10"
```

### Developer Category Search

Search the [Developer Index](/features/developer) for primary sources on a coding question:

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "how do I configure retries",
    "categories": ["developer"],
    "limit": 10
  }'
```

Developer results come back in the standard `web` group, each carrying `category: "developer"`; the `developer` category cannot be combined with other categories. For ranked results with the matched passages, and for the repository and documentation-source filters, use the [developer search endpoint](/features/developer#search-the-developer-index).

### Mixed Category Search

Combine multiple categories in one search:

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "neural networks",
    "categories": ["research", "pdf"],
    "limit": 15
  }'
```

## Domain Filters

Use `includeDomains` to restrict search results to specific domains, or `excludeDomains` to remove specific domains from the search. These fields add `site:` and `-site:` operators to the query internally, so pass domains only without a protocol or path.

<Note>
  `includeDomains` and `excludeDomains` are mutually exclusive. Use one or the other in a single request.
</Note>

### Include Domains

```bash cURL
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",
    "includeDomains": ["firecrawl.dev", "docs.firecrawl.dev"],
    "limit": 10
  }'
```

### Exclude Domains

```bash cURL
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 tools",
    "excludeDomains": ["example.com"],
    "limit": 10
  }'
```

### Category Response Format

Each search result includes a `category` field indicating its source:

```json
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://arxiv.org/abs/2024.12345",
        "title": "Advances in Neural Network Architecture",
        "description": "Research paper on neural network improvements",
        "category": "research"
      },
      {
        "url": "https://example.com/neural-networks.pdf",
        "title": "Neural Networks Survey",
        "description": "A survey of neural network architectures",
        "category": "pdf"
      }
    ]
  }
}
```

Examples:

```bash cURL
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
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "jupiter",
    "sources": ["images"],
    "limit": 8
  }'
```

### HD Image Search with Size Filtering

Use images operators to find high-resolution images:

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

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "mountain wallpaper larger:2560x1440",
    "sources": ["images"],
    "limit": 8
  }'
```

**Common HD resolutions:**
- `imagesize:1920x1080` - Full HD (1080p)
- `imagesize:2560x1440` - QHD (1440p)  
- `imagesize:3840x2160` - 4K UHD
- `larger:1920x1080` - HD and above
- `larger:2560x1440` - QHD and above

## Search with Content Scraping

Search and retrieve content from the search results in one operation.

<CodeGroup>

  <SearchContentPython />

  <SearchContentNode />

  <SearchContentCURL />

  <SearchContentCLI />

</CodeGroup>

Every option in scrape endpoint is supported by this search endpoint through the `scrapeOptions` parameter.

### Response with Scraped Content

```json
{
  "success": true,
  "data": [
    {
      "title": "Firecrawl - The Ultimate Web Scraping API",
      "description": "Firecrawl is a powerful web scraping API that turns any website into clean, structured data for AI and analysis.",
      "url": "https://firecrawl.dev/",
      "markdown": "# Firecrawl\n\nThe Ultimate Web Scraping API\n\n## Turn any website into clean, structured data\n\nFirecrawl makes it easy to extract data from websites for AI applications, market research, content aggregation, and more...",
      "links": [
        "https://firecrawl.dev/pricing",
        "https://firecrawl.dev/docs",
        "https://firecrawl.dev/guides"
      ],
      "metadata": {
        "title": "Firecrawl - The Ultimate Web Scraping API",
        "description": "Firecrawl is a powerful web scraping API that turns any website into clean, structured data for AI and analysis.",
        "sourceURL": "https://firecrawl.dev/",
        "statusCode": 200
      }
    }
  ]
}
```

## Search then Scrape (Two-Step Pattern)

If you need to filter or process search results before scraping, use a two-step approach: search first, then scrape the URLs you want.

<CodeGroup>

```python Python
from firecrawl import Firecrawl

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

# Step 1: Search
results = firecrawl.search("firecrawl web scraping", limit=5)

# Step 2: Scrape each result URL for full content
for item in results.web or []:
    page = firecrawl.scrape(item.url, formats=["markdown"])
    print(page.markdown[:200])
```

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

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

// Step 1: Search
const results = await firecrawl.search("firecrawl web scraping", { limit: 5 });

// Step 2: Scrape each result URL for full content
for (const item of results.web ?? []) {
  const page = await firecrawl.scrape(item.url, { formats: ["markdown"] });
  console.log(page.markdown?.substring(0, 200));
}
```

</CodeGroup>

<Tip>
**When to use which approach:**
- **One-step** (`scrapeOptions` in search): You want content from all results. Simpler and faster.
- **Two-step** (search then scrape): You want to filter, rank, or selectively scrape results. More flexible.

Both approaches use Firecrawl for the scrape step. Do not use generic HTTP fetching or summarize from search snippets alone -- the full page content from Firecrawl scrape is what makes results grounded and complete.
</Tip>

## Advanced Search Options

Firecrawl's search API supports various parameters to customize your search:

### Location Customization

<CodeGroup>

  <SearchLocationPython />

  <SearchLocationNode />

  <SearchLocationCURL />

  <SearchLocationCLI />

</CodeGroup>

### Time-Based Search

Use the `tbs` parameter to filter results by time. Note that `tbs` only applies to `web` source results — it does not filter `news` or `images` results. If you need time-filtered news, consider using a `web` source with the `site:` operator to target specific news domains.

<CodeGroup>

  <SearchTimePython />

  <SearchTimeNode />

  <SearchTimeCURL />

  <SearchTimeCLI />

</CodeGroup>

Common `tbs` values:
- `qdr:h` - Past hour
- `qdr:d` - Past 24 hours
- `qdr:w` - Past week
- `qdr:m` - Past month
- `qdr:y` - Past year
- `sbd:1` - Sort by date (newest first)

For more precise time filtering, you can specify exact date ranges using the custom date range format:

<CodeGroup>

```python Python
from firecrawl import Firecrawl

# Initialize the client with your API key
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# Search for results from December 2024
search_result = firecrawl.search(
    "firecrawl updates",
    limit=10,
    tbs="cdr:1,cd_min:12/1/2024,cd_max:12/31/2024"
)
```

```js JavaScript
import { Firecrawl } from 'firecrawl';

// Initialize the client with your API key
const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

// Search for results from December 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
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>

You can combine `sbd:1` with time filters to get date-sorted results within a time range. For example, `sbd:1,qdr:w` returns results from the past week sorted newest first, and `sbd:1,cdr:1,cd_min:12/1/2024,cd_max:12/31/2024` returns results from December 2024 sorted by date.

### Custom Timeout

Set a custom timeout for search operations:

<CodeGroup>

```python Python
from firecrawl import Firecrawl

# Initialize the client with your API key
firecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")

# Set a 30-second timeout
search_result = firecrawl.search(
    "complex search query",
    limit=10,
    timeout=30000  # 30 seconds in milliseconds
)
```

```js JavaScript
import { Firecrawl } from 'firecrawl';

// Initialize the client with your API key
const firecrawl = new Firecrawl({apiKey: "fc-YOUR_API_KEY"});

// Set a 30-second timeout
firecrawl.search("complex search query", {
  limit: 10,
  timeout: 30000  // 30 seconds in milliseconds
})
.then(searchResult => {
  // Process results
  console.log(searchResult.data);
});
```

```bash cURL
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>

### Safe Search

Set `safe` to `true` to filter explicit content from your search results (SafeSearch). When omitted, results are returned unfiltered, exactly as before.

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "firecrawl",
    "safe": true
  }'
```

## Zero Data Retention (ZDR)

For teams with strict data handling requirements, Firecrawl offers Zero Data Retention (ZDR) options for the `/search` endpoint via the `enterprise` parameter. ZDR search is available on Enterprise plans — visit [firecrawl.dev/enterprise](https://www.firecrawl.dev/enterprise) to get started.

<Note>
This is separate from the `zeroDataRetention` scrape option, which controls ZDR for scraping operations. See [Scrape ZDR](/features/scrape#zero-data-retention-zdr) for details. The `enterprise` parameter only applies to the search portion of the request.
</Note>

### End-to-End ZDR

With end-to-end ZDR, both Firecrawl and our upstream search provider enforce zero data retention. No query or result data is stored at any point in the pipeline.

- **Cost:** 10 credits per 10 results
- **Parameter:** `enterprise: ["zdr"]`

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 10,
    "enterprise": ["zdr"]
  }'
```

### Anonymized ZDR

With anonymized ZDR, Firecrawl enforces full zero data retention on our side. Our search provider may cache the query, but it is fully anonymized — no identifying information is attached.

- **Cost:** 2 credits per 10 results
- **Parameter:** `enterprise: ["anon"]`

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 10,
    "enterprise": ["anon"]
  }'
```

### Combining Search ZDR with Scrape ZDR

If you are using search with content scraping (`scrapeOptions`), the `enterprise` parameter automatically enforces ZDR for any resulting scrapes. The following example request enforces ZDR on both the search and scrape portions of the process:

```bash cURL
curl -X POST https://api.firecrawl.dev/v2/search \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer fc-YOUR_API_KEY" \
  -d '{
    "query": "sensitive topic",
    "limit": 5,
    "enterprise": ["zdr"],
    "scrapeOptions": {
      "formats": ["markdown"]
    }
  }'
```

## Cost Implications

The cost of a search is 2 credits per 10 results, rounded up (1–10 results = 2 credits, 11–20 = 4 credits, and so on). If scraping options are enabled, the standard scraping costs apply to each search result:

- **Basic scrape**: 1 credit per webpage
- **PDF parsing**: 1 credit per PDF page
- **JSON mode**: 4 additional credits per webpage

To help control costs:

- Set `parsers: []` if PDF parsing isn’t required
- Limit the number of search results with the `limit` parameter

## Advanced Scraping Options

For more details about the scraping options, refer to the [Scrape Feature documentation](https://docs.firecrawl.dev/features/scrape). Everything except for the FIRE-1 Agent and Change-Tracking features are supported by this Search endpoint.

> Are you an AI agent that needs a Firecrawl API key? See [firecrawl.dev/agent-onboarding/SKILL.md](https://www.firecrawl.dev/agent-onboarding/SKILL.md) for automated onboarding instructions.

## Search feedback

When a search result is useful or misses important content, submit feedback with `POST /v2/search/{jobId}/feedback`. The first feedback submission for a search job can refund 1 credit, subject to team limits, and helps improve Firecrawl search quality. See [Search Feedback](/api-reference/endpoint/search-feedback).