Search

2 min read

post/search

Request example

curl --request POST \
  --url https://api.firecrawl.dev/v1/search \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "query": "<string>",
  "limit": 5,
  "tbs": "<string>",
  "location": "<string>",
  "timeout": 60000,
  "ignoreInvalidURLs": false,
  "scrapeOptions": {},
  "threatProtection": {
    "mode": "off",
    "riskScoreThreshold": 75,
    "blacklist": [
      "<string>"
    ],
    "whitelist": [
      "<string>"
    ],
    "blockedTlds": [
      "<string>"
    ],
    "failurePolicy": "open"
  }
}'

Response

{
  "success": true,
  "data": [
    {
      "title": "<string>",
      "description": "<string>",
      "url": "<string>",
      "markdown": "<string>",
      "html": "<string>",
      "rawHtml": "<string>",
      "links": [
        "<string>"
      ],
      "screenshot": "<string>",
      "metadata": {
        "title": "<string>",
        "description": "<string>",
        "sourceURL": "<string>",
        "statusCode": 1,
        "numPages": 1,
        "totalPages": 1,
        "error": "<string>"
      }
    }
  ],
  "warning": "<string>",
  "id": "<string>"
}

post/search

Note: A new v2 version of this API is now available with improved features and performance.

The search endpoint combines web search with Firecrawl's scraping capabilities to return full page content for any query.

Include scrapeOptions with formats: ["markdown"] to get complete markdown content for each search result otherwise you will default to getting the results (url, title, description).

Supported query operators#

We support a variety of query operators that allow you to filter your searches better.

Operator	Functionality	Examples
`""`	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 website	`site:firecrawl.dev`
`inurl:`	Only returns results that include a word in the URL	`inurl:firecrawl`
`allinurl:`	Only returns results that include multiple words in the URL	`allinurl:git firecrawl`
`intitle:`	Only returns results that include a word in the title of the page	`intitle:Firecrawl`
`allintitle:`	Only returns results that include multiple words in the title of the page	`allintitle:firecrawl playground`
`related:`	Only returns results that are related to a specific domain	`related:firecrawl.dev`

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.

Time-Based Search#

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.

Authorization

Authorizationstringheaderrequired#

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

Body

application/json

querystringrequired#

The search query

limitinteger#

Maximum number of results to return

Default: 5

Range: 1–100

tbsstring#

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)

locationstring#

Location parameter for search results

timeoutinteger#

Timeout in milliseconds

Default: 60000

ignoreInvalidURLsboolean#

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.

Default: false

scrapeOptionsobject#

Options for scraping search results

Default: {}

Show child attributes

onlyMainContentboolean#

Only return the main content of the page excluding headers, navs, footers, etc.

Default: true

includeTagsstring[]#

Tags to include in the output.

excludeTagsstring[]#

Tags to exclude from the output.

maxAgeinteger#

Returns a cached version of the page if it is younger than this age in milliseconds. If a cached version of the page is older than this value, the page will be scraped. If you do not need extremely fresh data, enabling this can speed up your scrapes by 500%. Defaults to 0, which disables caching.

Default: 0

headersobject#

Headers to send with the request. Can be used to send cookies, user-agent, etc.

waitForinteger#

Specify a delay in milliseconds before fetching the content, allowing the page sufficient time to load.

Default: 0

mobileboolean#

Set to true if you want to emulate scraping from a mobile device. Useful for testing responsive pages and taking mobile screenshots.

Default: false

skipTlsVerificationboolean#

Skip TLS certificate verification when making requests

Default: false

timeoutinteger#

Timeout in milliseconds for the request

Default: 30000

parsePDFboolean#

Controls how PDF files are processed during scraping. When true, the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When false, the PDF file is returned in base64 encoding with a flat rate of 1 credit total.

Default: true

jsonOptionsobject#

JSON options object

Show child attributes

schemaobject#

The schema to use for the extraction (Optional). Must conform to JSON Schema.

systemPromptstring#

The system prompt to use for the extraction (Optional)

promptstring#

The prompt to use for the extraction without a schema (Optional)

checkPromptInjectionboolean#

When enabled, scans the scraped page content for prompt injection attempts before running the extraction. If an injection is detected, the request fails with a 403 and error code SCRAPE_PROMPT_INJECTION_DETECTED. Adds 4 credits when the check runs. Defaults to false.

Default: false

actionsobject[]#

Actions to perform on the page before grabbing the content

Show child attributes

One of

typeenum<string>required#

Wait for a specified amount of milliseconds

Options:wait

millisecondsinteger#

Number of milliseconds to wait

Range: >= 1

selectorstring#

Query selector to find the element by

typeenum<string>required#

Take a screenshot. The links will be in the response's actions.screenshots array.

Options:screenshot

fullPageboolean#

Whether to capture a full-page screenshot or limit to the current viewport.

Default: false

qualityinteger#

The quality of the screenshot, from 1 to 100. 100 is the highest quality.

typeenum<string>required#

Click on an element

Options:click

selectorstringrequired#

Query selector to find the element by

allboolean#

Clicks all elements matched by the selector, not just the first one. Does not throw an error if no elements match the selector.

Default: false

typeenum<string>required#

Write text into an input field, text area, or contenteditable element. Note: You must first focus the element using a 'click' action before writing. The text will be typed character by character to simulate keyboard input.

Options:write

textstringrequired#

Text to type

typeenum<string>required#

Press a key on the page

Options:press

keystringrequired#

Key to press

typeenum<string>required#

Scroll the page or a specific element

Options:scroll

directionenum<string>#

Direction to scroll

Default: "down"

Options:updown

selectorstring#

Query selector for the element to scroll

typeenum<string>required#

Scrape the current page content, returns the url and the html.

Options:scrape

typeenum<string>required#

Execute JavaScript code on the page

Options:executeJavascript

scriptstringrequired#

JavaScript code to execute

typeenum<string>required#

Generate a PDF of the current page. The PDF will be returned in the actions.pdfs array of the response.

Options:pdf

formatenum<string>#

The page size of the resulting PDF

Default: "Letter"

Options:A0A1A2A3A4A5A6LetterLegalTabloidLedger

landscapeboolean#

Whether to generate the PDF in landscape orientation

Default: false

scalenumber#

The scale multiplier of the resulting PDF

Default: 1

locationobject#

Location settings for the request. When specified, this will use an appropriate proxy if available and emulate the corresponding language and timezone settings. Defaults to 'US' if not specified.

Show child attributes

countrystring#

ISO 3166-1 alpha-2 country code (e.g., 'US', 'AU', 'DE', 'JP')

Default: "US"

Pattern: ^[A-Z]{2}$

languagesstring[]#

Preferred languages and locales for the request in order of priority. Defaults to the language of the specified location. See https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language

removeBase64Imagesboolean#

Removes all base 64 images from the output, which may be overwhelmingly long. The image's alt text remains in the output, but the URL is replaced with a placeholder.

Default: true

blockAdsboolean#

Enables ad-blocking and cookie popup blocking.

Default: true

proxyenum<string>#

Specifies the type of proxy to use.

basic: Proxies for scraping sites with none to basic anti-bot solutions. Fast and usually works.
enhanced: Enhanced proxies for scraping sites with advanced anti-bot solutions. Slower, but more reliable on certain sites. Billed at the same credit cost as basic.
auto: Firecrawl will automatically retry scraping with enhanced proxies if the basic proxy fails. Enhanced proxies carry no credit surcharge, so either way only the regular cost is billed.

If you do not specify a proxy, Firecrawl will default to basic.

Options:basicenhancedauto

storeInCacheboolean#

If true, the page will be stored in the Firecrawl index and cache. Setting this to false is useful if your scraping activity may have data protection concerns. Using some parameters associated with sensitive scraping (actions, headers) will force this parameter to be false.

Default: true

threatProtectionobject#

Per-request Threat Protection override. Fields you provide replace the corresponding fields of your organization's policy for this request only; omitted fields keep their organization-level values. Requires Threat Protection to be enabled for your team (enterprise feature) — otherwise the request is rejected with a 403. If your organization has disabled request overrides, any request that includes this object is rejected with a 403. If Threat Protection is enforced for your team, mode may not be set to off.

Show child attributes

modeenum<string>#

URL scanning mode for this request. normal checks URLs against Google Web Risk (+2 credits per URL scanned).

Options:offnormal

riskScoreThresholdinteger#

Normalized risk score (0–100) at or above which a classifier verdict blocks the URL. Lower is stricter.

Range: 0–100

blackliststring[]#

Domains to always block, as plain domains (example.com) or wildcard globs (*.example.com). No protocol, path, or port.

Items: max 1000

whiteliststring[]#

Domains to always allow, as plain domains or wildcard globs. Wins over every other rule.

Items: max 1000

blockedTldsstring[]#

Top-level domains to block outright, lowercase without the leading dot (e.g. zip).

Items: max 1000

failurePolicyenum<string>#

What to do when the classifier can't be reached: closed blocks the request, open allows it.

Options:openclosed

formatsenum<string>[]#

Default: []

threatProtectionobject#

Show child attributes

modeenum<string>#

URL scanning mode for this request. normal checks URLs against Google Web Risk (+2 credits per URL scanned).

Options:offnormal

riskScoreThresholdinteger#

Normalized risk score (0–100) at or above which a classifier verdict blocks the URL. Lower is stricter.

Range: 0–100

blackliststring[]#

Domains to always block, as plain domains (example.com) or wildcard globs (*.example.com). No protocol, path, or port.

Items: max 1000

whiteliststring[]#

Domains to always allow, as plain domains or wildcard globs. Wins over every other rule.

Items: max 1000

blockedTldsstring[]#

Top-level domains to block outright, lowercase without the leading dot (e.g. zip).

Items: max 1000

failurePolicyenum<string>#

What to do when the classifier can't be reached: closed blocks the request, open allows it.

Options:openclosed

Responses

application/json

Successful response

successboolean#

dataobject[]#

Show child attributes

titlestring#

Title from search result

descriptionstring#

Description from search result

urlstring#

URL of the search result

markdownstring#

Markdown content if scraping was requested

htmlstring#

HTML content if requested in formats

rawHtmlstring#

Raw HTML content if requested in formats

linksstring[]#

Links found if requested in formats

screenshotstring#

Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded.

metadataobject#

Show child attributes

titlestring · string[]#

Title extracted from the page, can be a string or array of strings

Show child attributes

One of

descriptionstring · string[]#

Description extracted from the page, can be a string or array of strings

Show child attributes

One of

sourceURLstring#

statusCodeinteger#

numPagesinteger#

For PDF inputs, the number of pages parsed (capped by the parsers maxPages option).

totalPagesinteger#

For PDF inputs, the document's true page count before any maxPages capping. Omitted when it cannot be determined; a totalPages greater than numPages indicates the result was truncated.

errorstring#

warningstring#

Warning message if any issues occurred

idstring#

The ID of the search job

Map Extract