Skip to main content

Search

3 min read
post/search
Request example
Response
post/search

The search endpoint combines web search 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 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
filetype:Only returns results with a specific file extensionfiletype:pdf, -filetype:pdf
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".

Categories Parameter#

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
  • pdf: Search for PDFs
  • developer: Search the Developer Index — 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 this endpoint's web results to a fixed list of academic domains.

To search scientific literature directly — paper abstracts across PubMed, bioRxiv, medRxiv, and arXiv, plus in-paper passage reads and citation-graph expansion — use the Research Index at GET /search/research/papers.

Example Usage#

Domain Filters#

Use includeDomains to restrict results to specific domains, or excludeDomains to remove specific domains from the search. Domains should be hostnames only, without protocol or path.

includeDomains and excludeDomains are mutually exclusive.

Include Domains Example#

Exclude Domains Example#

Category Response#

Each result includes a category field indicating its source:

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.

Are you an AI agent that needs a Firecrawl API key? See firecrawl.dev/agent-onboarding/SKILL.md for automated onboarding instructions.

Authorization

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

Body

application/json
querystringrequired#
The search query

Length: max 500

limitinteger#
Maximum number of results to return (per source type when using multiple sources)

Default: 10

Range: 1–100

sourcesobject[]#
Sources to search. Will determine the arrays available in the response. Defaults to ['web'].

Default: ["web"]

Show child attributes
categoriesobject[]#
Categories to filter results by. Defaults to [], which means results will not be filtered by any categories.
Show child attributes
includeDomainsstring[]#
Restricts search results to the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with excludeDomains.
excludeDomainsstring[]#
Excludes search results from the specified domains. Domains should be hostnames only, without protocol or path. Cannot be used with includeDomains.
tbsstring#
Time-based search parameter. Supports predefined time ranges (qdr:h, qdr:d, qdr:w, qdr:m, qdr:y), custom date ranges (cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY), and sort by date (sbd:1). Values can be combined, e.g. sbd:1,qdr:w.
locationstring#
Location parameter for search results (e.g. San Francisco,California,United States). For best results, set both this and the country parameter.
countrystring#
ISO country code for geo-targeting search results (e.g. US). For best results, set both this and the location parameter.

Default: "US"

safeboolean#
When true, filters explicit content from search results (SafeSearch). Omit to keep the default behavior, which does not apply the filter.
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

highlightsboolean#
Generate query-relevant highlights for search results. Set to false to return provider descriptions or snippets without highlighting.

Default: true

enterpriseenum<string>[]#
Enterprise search options for Zero Data Retention (ZDR). Use ["zdr"] for end-to-end ZDR (10 credits / 10 results) or ["anon"] for anonymized ZDR (2 credits / 10 results). Must be enabled for your team.
scrapeOptionsobject#
Options for scraping search results

Default: {}

Show child attributes
formatsobject[]#
Output formats to include in the response. You can specify one or more formats, either as strings (e.g., 'markdown') or as objects with additional options (e.g., { type: 'json', schema: {...} }). Some formats require specific options to be set. Example: ['markdown', { type: 'json', schema: {...} }].

Default: ["markdown"]

Show child attributes
onlyMainContentboolean#
Only return the main content of the page excluding headers, navs, footers, etc. This is a deterministic HTML-level filter applied before markdown is generated; no LLM is involved.

Default: true

onlyCleanContentboolean#
Beta. Run an additional LLM-based pass over the generated markdown to remove residual boilerplate that onlyMainContent can miss (cookie banners, ad blocks, social share widgets, breadcrumbs, newsletter signups, comment sections, related-article lists). Headings, lists, tables, code blocks, image references, and inline links are preserved. Can be combined with onlyMainContent (the most common setup) or used on its own. Skipped with a warning when the markdown exceeds the cleaning model's output token limit (the original markdown is preserved). Not supported on zero-data-retention requests.

Default: false

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

Default: 172800000

minAgeinteger#
When set, the request only checks the cache and never triggers a fresh scrape. The value is in milliseconds and specifies the minimum age the cached data must be. If matching cached data exists, it is returned instantly. If no cached data is found, a 404 with error code SCRAPE_NO_CACHED_DATA is returned. Set to 1 to accept any cached data regardless of age.
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. This waiting time is in addition to Firecrawl's smart wait feature.

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: true

timeoutinteger#
Timeout in milliseconds for the request. Minimum is 1000 (1 second). Default is 60000 (60 seconds). Maximum is 300000 (300 seconds).

Default: 60000

Range: 1000–300000

parsersobject[]#
Controls how files are processed during scraping. When "pdf" is included (default), the PDF content is extracted and converted to markdown format, with billing based on the number of pages (1 credit per page). When an empty array is passed, the PDF file is returned in base64 encoding with a flat rate of 1 credit for the entire PDF.

Default: ["pdf"]

Show child attributes
actionsobject[]#
Actions to perform on the page before grabbing the content
Show child attributes
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 markdown output, which may be overwhelmingly long. This does not affect html or rawHtml formats. 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.

Default: "auto"

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 (e.g. actions, headers) will force this parameter to be false.

Default: true

lockdownboolean#
If true, serves the request from Firecrawl's cache only and never makes an outbound request to the target URL. Designed for compliance-constrained or air-gapped environments where the scrape request itself could leak sensitive information. On cache miss, returns a 404 with error code SCRAPE_LOCKDOWN_CACHE_MISS (the URL is never logged on miss). Lockdown requests are treated as zero data retention. Default maxAge is extended to 2 years so existing cached pages remain eligible. Billed at 5 credits on hit, 1 credit on cache miss.

Default: false

redactPIIboolean · object#
Redact personally identifiable information from returned markdown. Pass true to use defaults, or an object to tune mode, entities, and replacement style.

Default: false

Show child attributes
profileobject#
Enable persistent browser storage across scrape and interact sessions. Pass a profile when scraping to preserve cookies, localStorage, and session data. Sessions with the same profile name share browser state.
Show child attributes
namestringrequired#
A name for the profile. Scrapes with the same name share browser state (cookies, localStorage, sessions).

Length: 1–128

saveChangesboolean#
When true, browser state is saved back to the profile when the interact session stops. Set to false to load existing data without writing. Only one saving session is allowed at a time.

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
auditMetadataobject#
User attribution included with SIEM logging events when SIEM Logging is enabled for the organization.
Show child attributes
usernamestringrequired#
The username associated with the request.

Length: max 1024

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

Responses

application/json
Successful response
successboolean#
dataobject#
The search results. The arrays available will depend on the sources you specified in the request. By default, the web array will be returned.
Show child attributes
webobject[]#
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
screenshotstring#
Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded.
audiostring#
Signed URL to the extracted MP3 audio file if audio is in formats. The signed URL expires after 1 hour.
videostring#
Signed URL to the extracted video file if video is in formats. The signed URL expires after 1 hour.
metadataobject#
Show child attributes
titlestring#
descriptionstring#
sourceURLstring#
The original URL that was requested. May differ from the page's final URL if redirects occurred.
urlstring#
The final URL of the page after all redirects have been followed.
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#
imagesobject[]#
Show child attributes
titlestring#
Title from search result
imageUrlstring#
URL of the image
imageWidthinteger#
Width of the image
imageHeightinteger#
Height of the image
urlstring#
URL of the search result
positioninteger#
Position of the search result
newsobject[]#
Show child attributes
titlestring#
Title of the article
snippetstring#
Snippet from the article
urlstring#
URL of the article
datestring#
Date of the article
imageUrlstring#
Image URL of the article
positioninteger#
Position of the article
markdownstring#
Markdown content if scraping was requested
htmlstring#
HTML content if requested in formats
rawHtmlstring#
Raw HTML content if requested in formats
screenshotstring#
Screenshot URL if requested in formats. Screenshots expire after 24 hours and can no longer be downloaded.
audiostring#
Signed URL to the extracted MP3 audio file if audio is in formats. The signed URL expires after 1 hour.
videostring#
Signed URL to the extracted video file if video is in formats. The signed URL expires after 1 hour.
metadataobject#
Show child attributes
titlestring#
descriptionstring#
sourceURLstring#
The original URL that was requested. May differ from the page's final URL if redirects occurred.
urlstring#
The final URL of the page after all redirects have been followed.
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
creditsUsedinteger#
The number of credits used for the search