firecrawl-search

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

firecrawl search

firecrawl 搜索

Web search with optional content scraping. Returns search results as JSON, optionally with full page content.

支持可选内容爬取的网页搜索。以JSON格式返回搜索结果，可选择附带全页面内容。

Quick start

快速开始

bash

undefined

bash

undefined

Basic search

基础搜索

firecrawl search "your query" -o .firecrawl/result.json --json

Search and scrape full page content from results

搜索并爬取结果中的全页面内容

firecrawl search "your query" --scrape -o .firecrawl/scraped.json --json

News from the past day

过去24小时的新闻

firecrawl search "your query" --sources news --tbs qdr:d -o .firecrawl/news.json --json


Run `firecrawl search --help` for the full option list.

`--categories developer` weighs the developer index beside ordinary web results in this same call (no passage control, no index filters). `--categories research` is a website filter, not the paper index. Dedicated skills: [firecrawl-developer-index](../firecrawl-developer-index/SKILL.md) and [firecrawl-research-index](../firecrawl-research-index/SKILL.md).

**Done when:** results are saved under `.firecrawl/`, verified non-empty, processed for the request, and one feedback event is sent within the time window (unless opted out).

firecrawl search "your query" --sources news --tbs qdr:d -o .firecrawl/news.json --json


运行`firecrawl search --help`查看完整选项列表。

`--categories developer`会在同一调用中同时参考开发者索引和普通网页结果（无段落控制、无索引筛选）。`--categories research`是网站筛选器，而非论文索引。专用技能：[firecrawl-developer-index](../firecrawl-developer-index/SKILL.md) 和 [firecrawl-research-index](../firecrawl-research-index/SKILL.md)。

**完成标志：** 结果已保存至`.firecrawl/`目录下，验证非空，已按请求处理，且在时间窗口内发送了一条反馈事件（除非选择退出）。

Tips

提示

--highlights
on by default: results are query-relevant excerpts, not full-page snippets. Use
```
--no-highlights
```
for the original snippets.
--scrape
fetches full content — reuse that content instead of re-scraping result URLs. This saves credits and avoids redundant fetches.
Always write results to
```
.firecrawl/
```
with
```
-o
```
to avoid context window bloat.

Use

jq

to extract URLs or titles:

jq -r '.data.web[].url' .firecrawl/search.json

Naming convention:

.firecrawl/search-{query}.json

.firecrawl/search-{query}-scraped.json

默认开启
--highlights
：结果为与查询相关的摘录，而非全页面片段。使用
```
--no-highlights
```
获取原始片段。
--scrape
会获取完整内容 —— 重复使用该内容，而非重新爬取结果URL。这样可以节省信用额度，避免重复请求。
始终使用
```
-o
```
将结果写入
```
.firecrawl/
```
目录，避免上下文窗口膨胀。

使用

jq

提取URL或标题：

jq -r '.data.web[].url' .firecrawl/search.json

命名规范：

.firecrawl/search-{query}.json

或

.firecrawl/search-{query}-scraped.json

Send feedback after every search (refunds 1 credit)

每次搜索后发送反馈（退还1个信用额度）

Search costs 2 credits. After you've actually used the results (or decided they were useless), send structured feedback with

firecrawl search-feedback <id>

. The first feedback per search refunds 1 credit and helps us improve search quality. Do this once per search, in the background, after you finish processing the results — it does not block your main task.

Opt out: if

FIRECRAWL_NO_SEARCH_FEEDBACK=1

(or

FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1

) is set, the CLI silently skips the call and never sends anything. Respect that — do not try to work around it. (Team admins can also disable this server-side; the API will return

feedbackErrorCode: "TEAM_OPTED_OUT"

and the CLI will exit 0 silently.)

Rules to know before you call this:

Time window: must be sent within ~2 minutes of the search. Late feedback is rejected.
--missing-content
is the most important field. It's a list of specific pieces of content you expected but did not find. One topic per entry, each in its own string. These aggregate across teams and tell us what to index next.
Substantive content required (zero-effort feedback is rejected with HTTP 400):
- ```
good
```
  → must include at least one
```
--valuable-sources
```
  entry.
- ```
partial
```
  → must include
```
--valuable-sources
```
  or
```
--missing-content
```
  .
- ```
bad
```
  → must include
```
--missing-content
```
  or
```
--query-suggestions
```
  .
Daily refund cap (per team, per UTC day, default 100 credits). Once your team has been refunded 100 credits today, further submissions still record feedback but no longer refund credits. The response includes
```
creditsRefundedToday
```
/
```
dailyRefundCap
```
/
```
dailyCapReached
```
. When
dailyCapReached: true
, stop calling
search-feedback
for the rest of the UTC day — it won't refund anything and you're wasting bandwidth.
Idempotent: re-submitting for the same search id returns success but no extra refund.
--silent &
is the right pattern — exit code 0 even on failure, so a rejected/expired call never crashes your pipeline.

Verify the search returned results before reading its

id

. Zero-result searches write no output file, so the file may be missing — or left over from an earlier search. The guard below skips feedback when the file is missing or has zero results; call

search-feedback

only inside it:

bash

undefined

搜索消耗2个信用额度。在实际使用结果后（或判定结果无用），使用

firecrawl search-feedback <id>

发送结构化反馈。每次搜索的首次反馈将退还1个信用额度，并帮助我们提升搜索质量。每个搜索仅发送一次，在后台完成，处理完结果后执行——不会阻塞你的主任务。

退出选项： 若设置

FIRECRAWL_NO_SEARCH_FEEDBACK=1

（或

FIRECRAWL_DISABLE_SEARCH_FEEDBACK=1

），CLI将静默跳过调用，永不发送任何内容。请遵守此设置——不要尝试绕过。（团队管理员也可在服务器端禁用此功能；API将返回

feedbackErrorCode: "TEAM_OPTED_OUT"

，CLI将静默退出，状态码为0。）

调用前需了解的规则：

时间窗口： 必须在搜索后约2分钟内发送。逾期反馈将被拒绝。
--missing-content
是最重要的字段。它是一个列表，包含你期望找到但未找到的具体内容片段。每个主题为一个条目，单独作为字符串。这些内容会在团队间汇总，帮助我们确定下一步要索引的内容。
需要实质性内容（零成本反馈将被HTTP 400拒绝）：
- ```
good
```
  → 必须包含至少一个
```
--valuable-sources
```
  条目。
- ```
partial
```
  → 必须包含
```
--valuable-sources
```
  或
```
--missing-content
```
  。
- ```
bad
```
  → 必须包含
```
--missing-content
```
  或
```
--query-suggestions
```
  。
每日退款上限（每个团队，每个UTC日，默认100个信用额度）。 一旦你的团队当日已获得100个信用额度退款，后续提交仍会记录反馈，但不再退款。响应中包含
```
creditsRefundedToday
```
/
```
dailyRefundCap
```
/
```
dailyCapReached
```
。当
dailyCapReached: true
时，当日剩余时间停止调用
search-feedback
——不会退款，还会浪费带宽。
幂等性： 同一搜索ID重复提交将返回成功，但不会额外退款。
--silent &
是正确的用法——即使失败也返回状态码0，因此被拒绝/过期的调用永远不会导致你的管道崩溃。

在读取搜索的

id

之前，先验证搜索是否返回了结果。无结果的搜索不会写入输出文件，因此文件可能不存在——或为之前搜索的遗留文件。下面的防护措施会在文件不存在或无结果时跳过反馈；仅在该防护内调用

search-feedback

：

bash

undefined

Send once per search. Rate honestly and replace the placeholder with the

每个搜索发送一次。如实评分，将占位符替换为实际情况对应的评分。所示的两个字段满足每种评分的实质性内容规则。

rating that matches what actually happened. The two fields shown

—

satisfy the substantive-content rule for every rating.

—

if SEARCH_ID=$(jq -er 'select(any(.data[]; length > 0)) | .id' .firecrawl/search-react-hooks.json); then firecrawl search-feedback "$SEARCH_ID"
--rating "<good|partial|bad>"
--valuable-sources '[{"url":"https://react.dev/reference/react/hooks","reason":"Most authoritative"}]'
--missing-content '[{"topic":"useDeferredValue","description":"No example of useDeferredValue with Suspense"}]'
--silent & fi


**`--missing-content` accepts:**

- JSON array of `{topic, description?}` objects (richest, preferred)
- `"topic: description"` strings (shorthand)
- Plain `"topic1, topic2, topic3"` (when you only have topic names)
- Repeated `--missing-content` flags

`--silent` suppresses output and `&` runs it in the background so feedback never blocks you.


**`--missing-content`接受以下格式：**

- `{topic, description?}`对象的JSON数组（最丰富，推荐使用）
- `"topic: description"`字符串（简写形式）
- 纯字符串`"topic1, topic2, topic3"`（仅包含主题名称时）
- 重复的`--missing-content`标志

`--silent`会抑制输出，`&`会在后台运行，因此反馈永远不会阻塞你的操作。

另请参阅

firecrawl-scrape — scrape a specific URL
firecrawl-map — discover URLs within a site
firecrawl-crawl — bulk extract from a site
firecrawl-developer-index — issues, merged PRs, READMEs, and docs
firecrawl-research-index — published papers, not
```
search --categories research
```

firecrawl-scrape —— 爬取特定URL
firecrawl-map —— 发现站点内的URL
firecrawl-crawl —— 批量提取站点内容
firecrawl-developer-index —— 问题、已合并PR、README和文档
firecrawl-research-index —— 已发表论文，而非
```
search --categories research
```

firecrawl-search

Original

Translation

firecrawl search

firecrawl 搜索

Quick start

快速开始

Basic search

基础搜索

Search and scrape full page content from results

搜索并爬取结果中的全页面内容

News from the past day

过去24小时的新闻

Tips

提示

Send feedback after every search (refunds 1 credit)

每次搜索后发送反馈（退还1个信用额度）

Send once per search. Rate honestly and replace the placeholder with the

每个搜索发送一次。如实评分，将占位符替换为实际情况对应的评分。所示的两个字段满足每种评分的实质性内容规则。

rating that matches what actually happened. The two fields shown

satisfy the substantive-content rule for every rating.

See also

另请参阅