Firecrawl Search
Search web, news, or image sources and return ranked results grouped by source. Provide a non-empty `query`; optionally set `sources` (web, images, or news), `limit` (1–100), time filter `tbs`, `filter`, `location`, `categories` (`github`, `research`, `pdf`, or `developer`), `enterprise`, and `highlights`. Use `includeDomains` to restrict results or `excludeDomains` to exclude hostnames; these fields are mutually exclusive. Search query operators include quoted phrases, `-term`, `site:host`, `inurl:term`, and `intitle:term`. You can provide `scrapeOptions` to extract selected content from returned pages in the same call, with options for formats, parsers, PDF handling, page content selection, screenshots, structured extraction, and related settings. Such fetches ignore `maxAge`; use the dedicated scrape operation when you need a live fetch. Search results normally contain a title, URL, and description, not the full page. Developer-category results are returned in `data.web` with `category: "developer"`; research-category web results are restricted to research-affiliated sites and include snippets. The synchronous response may include `success`, source-grouped `data` (such as `web`, `news`, `images`, or `alexandria`), `id` for optional search feedback, `creditsUsed`, `warning`, `error`, and follow-up/tool metadata such as `nextTool`, `feedbackTool`, `tools`, `agent_hints`, or `conversationId`. `includeDomains` and `excludeDomains` must not both be supplied. This operation does not provide asynchronous job submission or polling.
Pricing
The charge per call is (max(1.2 × actual search and page scraping usage, 0)) AE credits.
If you enable scraping for search results, the metered usage also includes the scraping performed during the call.
Parameters
Optional parameters use the platform defaults when omitted.
| Parameter | Type | Required | Description | Default |
|---|---|---|---|---|
tbs | string | No | Time-based search filter value. | — |
limit | integer | No | No parameter description. | — |
query | string | Yes | No parameter description. | — |
filter | string | No | Additional filter for search results. | — |
sources | array | No | Search sources to query, such as web, images, or news. | — |
sources[].type | enum (web | images | news) | Yes | No parameter description. | — |
location | string | No | Location settings used to localize search results. | — |
categories | array | No | No parameter description. | — |
enterprise | array | No | No parameter description. | — |
highlights | boolean | No | No parameter description. | — |
scrapeOptions | object | No | Options for scraping content from returned search-result pages. | — |
scrapeOptions.proxy | enum (basic | stealth | enhanced | auto) | No | No parameter description. | — |
scrapeOptions.maxAge | number | No | Maximum acceptable age of a cached result. | — |
scrapeOptions.mobile | boolean | No | Use a mobile browser viewport when scraping pages. | — |
scrapeOptions.formats | array | No | Output formats to generate when scraping search-result pages. | — |
scrapeOptions.parsers | array | No | Parsers to apply when processing scraped page content. | — |
scrapeOptions.profile | object | No | Browser profile settings used while scraping pages. | — |
scrapeOptions.profile.name | string | Yes | No parameter description. | — |
scrapeOptions.profile.saveChanges | boolean | No | Save changes made during the browser session to the profile. | — |
scrapeOptions.waitFor | number | No | Time to wait for page content to load before scraping. | — |
scrapeOptions.location | object | No | Location settings used when scraping pages. | — |
scrapeOptions.location.country | string | No | No parameter description. | — |
scrapeOptions.location.languages | array | No | Preferred languages for localized page retrieval. | — |
scrapeOptions.lockdown | boolean | No | No parameter description. | — |
scrapeOptions.redactPII | boolean | No | Redact personally identifiable information from scraped content. | — |
scrapeOptions.pdfOptions | object | No | Options for processing PDF content. | — |
scrapeOptions.pdfOptions.maxPages | integer | No | Maximum number of PDF pages to process. | — |
scrapeOptions.excludeTags | array | No | Exclude content within these HTML tags. | — |
scrapeOptions.includeTags | array | No | Include only content within these HTML tags. | — |
scrapeOptions.jsonOptions | object | No | Options for extracting structured JSON from scraped pages. | — |
scrapeOptions.jsonOptions.prompt | string | No | Instructions for extracting structured data from scraped page content. | — |
scrapeOptions.jsonOptions.schema | object | No | JSON schema that defines the structured data to extract from scraped pages. | — |
scrapeOptions.queryOptions | object | No | Options for querying scraped page content. | — |
scrapeOptions.queryOptions.mode | enum (directQuote | freeform) | Yes | No parameter description. | freeform |
scrapeOptions.queryOptions.prompt | string | Yes | Prompt used to query or extract information from scraped page content. | — |
scrapeOptions.storeInCache | boolean | No | Store scraped results in the cache for later reuse. | — |
scrapeOptions.onlyMainContent | boolean | No | Extract only the main page content and exclude navigation, headers, footers, and other boilerplate where possible. | — |
scrapeOptions.screenshotOptions | object | No | Options for screenshots captured while scraping pages. | — |
scrapeOptions.screenshotOptions.quality | number | No | Screenshot image quality setting. | — |
scrapeOptions.screenshotOptions.fullPage | boolean | No | Capture the full page instead of only the visible viewport. | — |
scrapeOptions.screenshotOptions.viewport | object | No | Viewport dimensions used when capturing screenshots. | — |
scrapeOptions.screenshotOptions.viewport.width | number | Yes | No parameter description. | — |
scrapeOptions.screenshotOptions.viewport.height | number | Yes | No parameter description. | — |
scrapeOptions.zeroDataRetention | boolean | No | Do not retain scraped data after processing. | — |
scrapeOptions.removeBase64Images | boolean | No | Remove Base64-encoded images from scraped content. | — |
scrapeOptions.skipTlsVerification | boolean | No | Skip TLS certificate verification when loading pages. | — |
excludeDomains | array | No | Exclude results from these domain hostnames. Do not include protocols or paths. Do not use with `includeDomains`. | — |
includeDomains | array | No | Restrict results to these domain hostnames. Do not include protocols or paths. Do not use with `excludeDomains`. | — |
Invocation example
Copy the request and explore its response example.
/agent-api/v1/tool/executeX-Api-Keycurl --request POST \
--url 'https://agentearth.ai/agent-api/v1/tool/execute?tool_name=ae_firecrawl_search' \
--header "X-Api-Key: $AGENTEARTH_API_KEY" \
--header 'Content-Type: application/json' \
--data-raw '{
"params": {
"limit": 10,
"query": "\"1097325847299\"",
"sources": [
{
"type": "web"
}
]
}
}'{
"agent_hints": [
"No web results were returned. If the task is still unresolved, use firecrawl_search again with {\"query\":\"<broader or alternative query>\",\"sources\":[\"web\"]}."
],
"conversationId": "184ee620-62bc-449f-b862-203a12f62b47",
"data": {
"tools": [
{
"capability": "audio-recordings/get_cylinder",
"description": "MP3 links, licence and credit for one cylinder, e.g. https://cylinders.library.ucsb.edu/detail.php?query_type=mms_id&query=9948000799203776, cylinder 17334, or http://www.library.ucsb.edu/OBJID/Cylinder17334.",
"provider": "cylinders-library-ucsb-edu"
}
],
"web": []
},
"id": "01a1caa0-2d03-7359-aaab-fe52373417d5",
"success": true
}This example shows part of the response. Copied content is valid JSON.
Guides using this tool
See how this tool fits into real workflows

