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

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

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.

categories
(GitHub · object | Research · object)[]

Categories to filter results by

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

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