Search

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

Performing a Search with Firecrawl#

/search endpoint#

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

Installation#

Basic Usage#

Response#

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

{  "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      },      ...    ]  }}

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

const result = await firecrawl.search("query");for (const item of result.web ?? []) {  console.log(item.url, item.title);}

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
• pdf: Search for PDFs
• developer: Search the Developer Index — issues, merged pull requests, and READMEs from public code repositories, alongside curated documentation sites

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:

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, which searches paper abstracts across PubMed, bioRxiv, medRxiv, and arXiv and can read passages from inside a paper:

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 for primary sources on a coding question:

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.

Mixed Category Search#

Combine multiple categories in one search:

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.

Include Domains#

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#

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:

{  "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:

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

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:

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

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.

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

Response with Scraped Content#

{  "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.

from firecrawl import Firecrawlfirecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")# Step 1: Searchresults = firecrawl.search("firecrawl web scraping", limit=5)# Step 2: Scrape each result URL for full contentfor item in results.web or []:    page = firecrawl.scrape(item.url, formats=["markdown"])    print(page.markdown[:200])

Advanced Search Options#

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

Location Customization#

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.

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:

from firecrawl import Firecrawl# Initialize the client with your API keyfirecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")# Search for results from December 2024search_result = firecrawl.search(    "firecrawl updates",    limit=10,    tbs="cdr:1,cd_min:12/1/2024,cd_max:12/31/2024")

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:

from firecrawl import Firecrawl# Initialize the client with your API keyfirecrawl = Firecrawl(api_key="fc-YOUR_API_KEY")# Set a 30-second timeoutsearch_result = firecrawl.search(    "complex search query",    limit=10,    timeout=30000  # 30 seconds in milliseconds)

Safe Search#

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

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 to get started.

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

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

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:

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