> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firecrawl.dev/llms.txt
> Use this file to discover all available pages before exploring further.
# Search
> 注意：现已推出该 API 的全新 [v2 版本](/zh/api-reference/endpoint/search)，功能与性能均有升级。
该 /search 端点将网页搜索与 Firecrawl 的抓取能力相结合，可为任意查询返回完整页面内容。
在请求中包含 `scrapeOptions` 并设置 `formats: ["markdown"]`，即可为每个搜索结果获取完整的 markdown 内容；否则将默认仅返回结果 (url、title、description) 。
## 支持的查询运算符
我们提供多种查询运算符，帮助你更精准地筛选搜索结果。
| 运算符 | 功能 | 示例 |
| ------------- | ------------------ | --------------------------------- |
| `""` | 对一段文本进行精确匹配 | `"Firecrawl"` |
| `-` | 排除特定关键词或对其他运算符取反 | `-bad`, `-site:firecrawl.dev` |
| `site:` | 仅返回来自指定网站的结果 | `site:firecrawl.dev` |
| `inurl:` | 仅返回在 URL 中包含某个词的结果 | `inurl:firecrawl` |
| `allinurl:` | 仅返回在 URL 中包含多个词的结果 | `allinurl:git firecrawl` |
| `intitle:` | 仅返回在页面标题中包含某个词的结果 | `intitle:Firecrawl` |
| `allintitle:` | 仅返回在页面标题中包含多个词的结果 | `allintitle:firecrawl playground` |
| `related:` | 仅返回与特定域名相关的结果 | `related:firecrawl.dev` |
## Location 参数
使用 `location` 参数获取按地理位置定向的搜索结果。格式："string"。示例："Germany"、"San Francisco,California,United States"。
请参阅[完整的支持位置列表](https://firecrawl.dev/search_locations.json)，了解所有可用的国家和语言。
## 基于时间的搜索
使用 `tbs` 参数按时间范围筛选结果，支持自定义日期区间。详见[搜索功能文档](https://docs.firecrawl.dev/features/search#time-based-search)，其中包含详细示例和支持的 formats。
## OpenAPI
````yaml zh/api-reference/v1-openapi.json POST /search
openapi: 3.0.0
info:
contact:
email: support@firecrawl.dev
name: Firecrawl Support
url: https://firecrawl.dev/support
description: 用于与 Firecrawl 服务交互，以进行网页抓取和爬取任务的 API。
title: Firecrawl API
version: v1
servers:
- url: https://api.firecrawl.dev/v1
security:
- bearerAuth: []
paths:
/search:
post:
tags:
- Search
summary: 搜索并按需抓取搜索结果
operationId: searchAndScrape
requestBody:
content:
application/json:
schema:
properties:
ignoreInvalidURLs:
default: false
description: >-
会从搜索结果中排除对其他 Firecrawl 端点无效的 URL。这样当你将搜索结果数据传递到其他 Firecrawl
API 端点时，可以减少出错。
type: boolean
limit:
default: 5
description: 返回的最大结果数
maximum: 100
minimum: 1
type: integer
location:
description: 搜索结果的 location 参数
type: string
query:
description: 搜索查询
type: string
scrapeOptions:
allOf:
- $ref: '#/components/schemas/BaseScrapeOptions'
- properties:
formats:
default: []
items:
enum:
- markdown
- html
- rawHtml
- links
- screenshot
- screenshot@fullPage
- json
- extract
type: string
type: array
type: object
default: {}
description: 搜索结果抓取选项
tbs:
description: >-
基于时间的搜索参数。支持预定义时间范围（`qdr:h`、`qdr:d`、`qdr:w`、`qdr:m`、`qdr:y`）以及自定义日期范围（`cdr:1,cd_min:MM/DD/YYYY,cd_max:MM/DD/YYYY`）。
type: string
threatProtection:
$ref: '#/components/schemas/ThreatProtectionOverride'
timeout:
default: 60000
description: 超时时间（毫秒）
type: integer
required:
- query
type: object
required: true
responses:
'200':
content:
application/json:
schema:
properties:
data:
items:
properties:
description:
description: 搜索结果中的描述
type: string
html:
description: 若在 formats 中指定，则返回 HTML 内容
nullable: true
type: string
links:
description: 如果在 formats 中有请求，则返回发现的链接
items:
type: string
type: array
markdown:
description: 在请求抓取时返回的 Markdown 内容
nullable: true
type: string
metadata:
properties:
description:
description: 从页面提取的描述，可以是字符串或字符串数组
oneOf:
- type: string
- items:
type: string
type: array
error:
nullable: true
type: string
numPages:
description: 对于 PDF 输入，表示已解析的页数（受 parser 的 maxPages 选项上限限制）。
type: integer
sourceURL:
type: string
statusCode:
type: integer
title:
description: 从页面中提取的标题，可以是字符串或字符串数组。
oneOf:
- type: string
- items:
type: string
type: array
totalPages:
description: >-
对于 PDF 输入，表示文档在未受 maxPages 限制前的实际总页数。若无法确定则省略；如果
totalPages 大于 numPages，则表示结果已被截断。
type: integer
type: object
rawHtml:
description: 如果在 formats 中请求，则会返回原始 HTML 内容
nullable: true
type: string
screenshot:
description: 如果在 formats 中请求了截图，将返回截图的 URL。截图在 24 小时后过期，之后将无法再下载。
nullable: true
type: string
title:
description: 来自搜索结果的标题
type: string
url:
description: 搜索结果的URL
type: string
type: object
type: array
id:
description: 搜索任务的 ID
type: string
success:
type: boolean
warning:
description: 出现问题时显示的警告信息
nullable: true
type: string
type: object
description: 成功响应
'408':
content:
application/json:
schema:
properties:
error:
example: Request timed out
type: string
success:
example: false
type: boolean
type: object
description: 请求超时
'500':
content:
application/json:
schema:
properties:
error:
example: An unexpected error occurred on the server.
type: string
success:
example: false
type: boolean
type: object
description: 服务器错误
security:
- bearerAuth: []
components:
schemas:
BaseScrapeOptions:
properties:
actions:
description: 在抓取页面内容前需要执行的 actions
items:
oneOf:
- properties:
milliseconds:
description: 等待的时间（毫秒）
minimum: 1
type: integer
selector:
description: 用于定位该元素的查询选择器
example: '#my-element'
type: string
type:
description: 等待指定的毫秒数
enum:
- wait
type: string
required:
- type
title: Wait
type: object
- properties:
fullPage:
default: false
description: 是否截取整页截图，或仅截取当前视口。
type: boolean
quality:
description: 截图质量，取值范围为 1 至 100，100 为最高质量。
type: integer
type:
description: 进行截图。链接将位于响应的 `actions.screenshots` 数组中。
enum:
- screenshot
type: string
required:
- type
title: Screenshot
type: object
- properties:
all:
default: false
description: 点击所有匹配该选择器的元素，而不仅仅是第一个元素。如果没有元素匹配该选择器，也不会抛出错误。
type: boolean
selector:
description: 用于查找元素的查询选择器
example: '#load-more-button'
type: string
type:
description: 单击元素
enum:
- click
type: string
required:
- type
- selector
title: Click
type: object
- properties:
text:
description: 输入文本
example: Hello, world!
type: string
type:
description: >-
在输入框、文本区域或 contenteditable
元素中写入文本。注意：在写入之前，必须先通过一次“click”操作使该元素获得焦点。文本将以逐字符输入的方式进行，以模拟键盘敲击。
enum:
- write
type: string
required:
- type
- text
title: Write text
type: object
- description: >-
请在页面上按下任意键。按键代码请参考：https://asawicki.info/nosense/doc/devices/keyboard/key_codes.html。
properties:
key:
description: 按键
example: Enter
type: string
type:
description: 在页面上按下任意键
enum:
- press
type: string
required:
- type
- key
title: Press a key
type: object
- properties:
direction:
default: down
description: 滚动方向
enum:
- up
- down
type: string
selector:
description: 需要滚动的元素的查询选择器
example: '#my-element'
type: string
type:
description: 滚动页面或特定元素
enum:
- scroll
type: string
required:
- type
title: Scroll
type: object
- properties:
type:
description: 抓取当前页面内容，同时返回其 URL 和 HTML。
enum:
- scrape
type: string
required:
- type
title: Scrape
type: object
- properties:
script:
description: 待执行的 JavaScript 代码
example: document.querySelector('.button').click();
type: string
type:
description: 在页面上执行 JavaScript 代码
enum:
- executeJavascript
type: string
required:
- type
- script
title: Execute JavaScript
type: object
- properties:
format:
default: Letter
description: 生成的 PDF 的页面大小
enum:
- A0
- A1
- A2
- A3
- A4
- A5
- A6
- Letter
- Legal
- Tabloid
- Ledger
type: string
landscape:
default: false
description: 是否以横向页面方向生成 PDF 文件
type: boolean
scale:
default: 1
description: 生成的 PDF 的缩放比例
type: number
type:
description: 生成当前页面的 PDF。该 PDF 将在响应中的 `actions.pdfs` 数组里返回。
enum:
- pdf
type: string
required:
- type
title: Generate PDF
type: object
type: array
blockAds:
default: true
description: 启用广告拦截和 Cookie 弹窗屏蔽。
type: boolean
excludeTags:
description: 在输出结果中要排除的标签。
items:
type: string
type: array
headers:
description: 随请求发送的请求头。可用于携带 cookies、user-agent 等信息。
type: object
includeTags:
description: 需要包含在输出中的标签。
items:
type: string
type: array
jsonOptions:
description: JSON 配置对象
properties:
prompt:
description: 在无 schema 情况下用于抽取的数据提示词（可选）
type: string
schema:
description: 用于提取的数据模式（可选）。必须符合 [JSON Schema](https://json-schema.org/) 规范。
type: object
systemPrompt:
description: 用于抽取的系统提示（可选）
type: string
type: object
location:
description: 请求的地理位置设置。指定后，如果可用，将使用合适的代理服务器，并模拟相应的语言和时区设置。如果未指定，默认值为“US”。
properties:
country:
default: US
description: ISO 3166-1 alpha-2 两位字母国家代码（例如：“US”、“AU”、“DE”、“JP”）
pattern: ^[A-Z]{2}$
type: string
languages:
description: >-
按照优先级为本次请求指定首选语言和区域设置。默认使用所指定地区的语言。详见：https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Accept-Language
items:
example: en-US
type: string
type: array
type: object
maxAge:
default: 0
description: >-
如果页面的缓存版本的生成时间距现在小于此值（毫秒），则返回该缓存版本；如果缓存版本早于此值，则会重新抓取页面。如果你不需要极其实时的数据，启用此选项可以将抓取速度最多提升
5 倍。默认值为 0，表示禁用缓存。
type: integer
mobile:
default: false
description: 若要模拟移动端抓取，请将其设置为 true。适用于测试响应式页面并获取移动端截图。
type: boolean
onlyMainContent:
default: true
description: 仅返回页面的主体内容，不包括页眉、导航、页脚等。
type: boolean
parsePDF:
default: true
description: >-
控制在爬取过程中如何处理 PDF 文件。为 true 时，会提取 PDF 内容并转换为 Markdown 格式，按页数计费（每页 1
个积分）。为 false 时，会返回以 base64 编码的 PDF 文件，统一按 1 个积分计费。
type: boolean
proxy:
description: |-
指定要使用的代理类型。
- **basic**：适用于抓取没有或仅有基础防爬机制网站的代理。速度快，通常足够好用。
- **enhanced**：适用于抓取具有高级防爬机制网站的增强型代理。速度较慢，但在某些网站上更可靠。每次请求最多消耗 5 个积分。
- **auto**：当使用 basic 代理抓取失败时，Firecrawl 会自动使用 enhanced 代理重试。如果使用 enhanced 重试成功，该次抓取将收取 5 个积分；如果首次使用 basic 即抓取成功，则只收取常规费用。
如果未指定代理类型，Firecrawl 将默认使用 basic。
enum:
- basic
- enhanced
- auto
type: string
removeBase64Images:
default: true
description: 从输出中移除所有 Base64 图片，以避免内容过于冗长。图片的替代文本（alt 文本）会保留在输出中，但其 URL 会被占位符替换。
type: boolean
skipTlsVerification:
default: false
description: 在发送请求时跳过 TLS 证书校验
type: boolean
storeInCache:
default: true
description: >-
如果为 true，该页面将被存储到 Firecrawl 的索引和缓存中。若你的抓取活动可能涉及数据保护方面的问题，将其设置为 false
会更合适。使用某些与敏感抓取相关的参数（如 actions、headers）时，该参数会被强制设为 false。
type: boolean
threatProtection:
$ref: '#/components/schemas/ThreatProtectionOverride'
timeout:
default: 30000
description: 请求超时时间（毫秒）
type: integer
waitFor:
default: 0
description: 设置在获取内容前的延迟时间（毫秒），以便页面有足够时间加载完成。
type: integer
type: object
ThreatProtectionOverride:
description: >-
此请求的 [威胁防护](https://docs.firecrawl.dev/features/threat-protection)
单次请求覆盖配置。你提供的字段只会替换本次请求中组织策略里的对应字段；未提供的字段将保留组织级别的值。你的团队必须已启用威胁防护（企业版功能），否则该请求将被
403 拒绝。如果你的组织已禁用单次请求覆盖，任何包含此对象的请求都会被 403 拒绝。如果你的团队强制启用了威胁防护，则不能将 `mode`
设为 `off`。
properties:
blacklist:
description: 始终封禁的域名，可为普通域名（`example.com`）或通配 glob（`*.example.com`）。不包含协议、路径或端口。
items:
type: string
maxItems: 1000
type: array
blockedTlds:
description: 要直接封禁的顶级域名，使用不带前导点的小写形式（例如 `zip`）。
items:
type: string
maxItems: 1000
type: array
failurePolicy:
description: 当无法访问分类器时的处理方式：`closed` 会封禁该请求，`open` 则会允许该请求。
enum:
- open
- closed
type: string
mode:
description: >-
此请求的 URL 扫描模式。`normal` 会根据 Google Web Risk 检查 URL（每扫描一个 URL 额外消耗 2
点额度）。
enum:
- 'off'
- normal
type: string
riskScoreThreshold:
description: 标准化风险分数阈值（0–100）：当分类器判定结果达到或超过该值时，URL 会被封禁。值越低，限制越严格。
example: 75
maximum: 100
minimum: 0
type: integer
whitelist:
description: 始终允许的域名，可为普通域名或通配 glob。其优先级高于其他所有规则。
items:
type: string
maxItems: 1000
type: array
title: Threat Protection Override
type: object
securitySchemes:
bearerAuth:
scheme: bearer
type: http
````