Skip to main content
POST
/
search
Search and optionally scrape search results
curl --request POST \
  --url https://api.firecrawl.dev/v2/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "limit": 5,
  "sources": [
    "web"
  ],
  "categories": [
    {
      "type": "github"
    }
  ],
  "tbs": "<string>",
  "location": "<string>",
  "country": "US",
  "timeout": 60000,
  "ignoreInvalidURLs": false,
  "scrapeOptions": {
    "formats": [
      "markdown"
    ],
    "onlyMainContent": true,
    "includeTags": [
      "<string>"
    ],
    "excludeTags": [
      "<string>"
    ],
    "maxAge": 172800000,
    "headers": {},
    "waitFor": 0,
    "mobile": false,
    "skipTlsVerification": true,
    "timeout": 123,
    "parsers": [
      "pdf"
    ],
    "actions": [
      {
        "type": "wait",
        "milliseconds": 2,
        "selector": "#my-element"
      }
    ],
    "location": {
      "country": "US",
      "languages": [
        "en-US"
      ]
    },
    "removeBase64Images": true,
    "blockAds": true,
    "proxy": "auto",
    "storeInCache": true
  }
}'
{
  "success": true,
  "data": {
    "web": [
      {
        "title": "<string>",
        "description": "<string>",
        "url": "<string>",
        "markdown": "<string>",
        "html": "<string>",
        "rawHtml": "<string>",
        "links": [
          "<string>"
        ],
        "screenshot": "<string>",
        "metadata": {
          "title": "<string>",
          "description": "<string>",
          "sourceURL": "<string>",
          "statusCode": 123,
          "error": "<string>"
        }
      }
    ],
    "images": [
      {
        "title": "<string>",
        "imageUrl": "<string>",
        "imageWidth": 123,
        "imageHeight": 123,
        "url": "<string>",
        "position": 123
      }
    ],
    "news": [
      {
        "title": "<string>",
        "snippet": "<string>",
        "url": "<string>",
        "date": "<string>",
        "imageUrl": "<string>",
        "position": 123,
        "markdown": "<string>",
        "html": "<string>",
        "rawHtml": "<string>",
        "links": [
          "<string>"
        ],
        "screenshot": "<string>",
        "metadata": {
          "title": "<string>",
          "description": "<string>",
          "sourceURL": "<string>",
          "statusCode": 123,
          "error": "<string>"
        }
      }
    ]
  },
  "warning": "<string>"
}

​
What’s New in v2

​
Search Multiple Sources

Search web, images, and news at once: 
{
  "query": "firecrawl web scraping",
  "sources": [ "web", "images", "news" ]
}

​
Response Format Changed

v1: flat list of results. v2: organized by source type: 
{
  "success": true,
  "data": {
    "web": [/* web results */],
    "images": [/* image results */],
    "news": [/* news results */]
  }
}

​
New Features

  • Filter by time ranges (“past week”, “past month”)
  • Target specific countries/regions
  • Category Filtering: Search within GitHub repositories or research websites
  • Results capped at 500 during alpha
The search endpoint combines web search (SERP) with Firecrawl’s scraping capabilities to return full page content for any query. Include scrapeOptions with formats: [{"type": "markdown"}] to get complete markdown content for each search result otherwise you will default to getting the SERP results (url, title, description). You can also use other formats like {"type": "summary"} for condensed content.

​
Supported query operators

We support a variety of query operators that allow you to filter your searches better.
OperatorFunctionalityExamples
""Non-fuzzy matches a string of text"Firecrawl"
-Excludes certain keywords or negates other operators-bad, -site:firecrawl.dev
site:Only returns results from a specified websitesite:firecrawl.dev
inurl:Only returns results that include a word in the URLinurl:firecrawl
allinurl:Only returns results that include multiple words in the URLallinurl:git firecrawl
intitle:Only returns results that include a word in the title of the pageintitle:Firecrawl
allintitle:Only returns results that include multiple words in the title of the pageallintitle:firecrawl playground
related:Only returns results that are related to a specific domainrelated:firecrawl.dev
imagesize:Only returns images with exact dimensionsimagesize:1920x1080
larger:Only returns images larger than specified dimensionslarger:1920x1080

​
Location Parameter

Use the location parameter to get geo-targeted search results. Format: "string". Examples: "Germany", "San Francisco,California,United States". See the complete list of supported locations for all available countries and languages.

​
Country Parameter

Use the country parameter to specify the country for search results using ISO country codes. Default: "US". Examples: "US", "DE", "FR", "JP", "UK", "CA". 
{
  "query": "restaurants",
  "country": "DE"
}

​
Categories Parameter

Filter search results by specific categories using the categories parameter:
  • github: Search within GitHub repositories, code, issues, and documentation
  • research: Search academic and research websites (arXiv, Nature, IEEE, PubMed, etc.)
  • pdf: Search for PDFs

​
Example Usage

{
  "query": "machine learning",
  "categories": ["github", "research"],
  "limit": 10
}

​
Category Response

Each result includes a category field indicating its source: 
{
  "success": true,
  "data": {
    "web": [
      {
        "url": "https://github.com/example/ml-project",
        "title": "Machine Learning Project",
        "description": "Implementation of ML algorithms",
        "category": "github"
      },
      {
        "url": "https://arxiv.org/abs/2024.12345",
        "title": "ML Research Paper",
        "description": "Latest advances in machine learning",
        "category": "research"
      }
    ]
  }
}
Use the tbs parameter to filter results by time periods, including custom date ranges. See the Search Feature documentation for detailed examples and supported formats.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
​
query
string
required

The search query

​
limit
integer
default:5

Maximum number of results to return

Required range: 1 <= x <= 100
​
sources
(Web · object | Images · object | News · object)[]

Sources to search. Will determine the arrays available in the response.

  • Web
  • Images
  • News
​
categories
(GitHub · object | Research · object | PDF · object)[]

Categories to filter results by

  • GitHub
  • Research
  • PDF
​
tbs
string

Time-based search parameter. Supports predefined time ranges (qdr:h, qdr:d, qdr:w, qdr:m, qdr:y) and custom date ranges (cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY)

​
location
string

Location parameter for search results (e.g. San Francisco,California,United States). For best results, set both this and the country parameter.

​
country
string
default:US

ISO country code for geo-targeting search results (e.g. US). For best results, set both this and the location parameter.

​
timeout
integer
default:60000

Timeout in milliseconds

​
ignoreInvalidURLs
boolean
default:false

Excludes URLs from the search results that are invalid for other Firecrawl endpoints. This helps reduce errors if you are piping data from search into other Firecrawl API endpoints.

​
scrapeOptions
object

Options for scraping search results

Response

Successful response

​
success
boolean
​
data
object

The search results. The arrays available will depend on the sources you specified in the request. By default, the web array will be returned.

​
warning
string | null

Warning message if any issues occurred