跳到正文
CrawlForge MCP
搜索Brave Search API5 credits

search_web

以 JSON 形式获取实时网页索引。结果来自 Brave Search API 的独立网页索引。每条结果包含标题、URL、摘要片段以及一份带高亮的摘要副本，另附一个元数据块，给出搜索耗时。站点和文件类型过滤会转换为搜索运算符；语言、时间范围和安全搜索则作为搜索过滤条件传入。

使用场景

研究流水线

先找到某个主题的信息源，再把 URL 直接送入 batch_scrape 或 extract_content。

站内搜索

设置 site 即可在单个域名内搜索——用来替代不存在或很难用的站内搜索框。

文档检索

把 file_type 与查询词结合，查找某个主题的 PDF、表格或幻灯片。

时效监测

用 time_range 限定最近一天或一周，捕捉某个主题或品牌的新报道。

竞争态势发现

查看实时网页搜索会为你关心的关键词呈现哪些页面。若要查看你在 Google 中的确切排名，请使用 serp_rank。

为智能体提供依据

给模型提供当下的搜索结果作为依据，而不是依赖它记住的内容。

Endpoint

POST/api/v1/tools/search_web
Auth Required
Free 计划 1 req/s
5 credits

Parameters

NameTypeRequiredDefaultDescription
query
stringOptional-
搜索词。`site:`、`filetype:` 和引号短语等运算符与在搜索框中输入的效果一致，`site` 和 `file_type` 会作为附加运算符追加上去。`query` 与 `queries` 必须且只能传其中一个。
Example: mcp server for web scraping
queries
string[]Optional-
在一次调用中运行 1 到 10 条搜索查询，用于替代 `query`。每条查询都会走与单条搜索相同的流程，返回的负载放在 `results_by_query` 中：这是一个按你发送顺序排列的列表，每条查询对应一个条目，带上它自己的 `query` 以及该次搜索的各个字段；若某条搜索失败，则该条目为 `query` 加 `error`。`queries` 原样回显你的输入，`count` 即其长度。一次 `search_web` 调用按每条返回了结果的查询收取 5 credits：单条 `query` 收 5，`queries` 批次预估为 5 × 发送的查询条数，该值是上限：失败的查询不计费，因此一条都没成功的批次不产生任何费用。 列表中重复的查询会执行两次，两次都返回结果时也计费两次。一条都没成功的批次仍然是 **200**，带回常规信封：`count` 与发送时一致、每条查询各一个 `{ query, error }` 条目，以及 `credits_used: 0`。`query` 与 `queries` 必须且只能传一个——两个都传或都不传都会返回 400。
Example: ["mcp server for web scraping", "model context protocol tools"]
limit
numberOptional10
返回的结果数，取值 1-100——但单次请求上限为 10，因此超过 10 的值等同于 10。
Example: 10
offset
numberOptional0
首条结果的下标，从 0 开始。翻页时依次用 10、20、30，最大到 90：第 100 条之后的结果无法获取，超出范围的页会返回空的 `results` 数组。每一页都是一次独立搜索，收取 5 credits。
Example: 10
lang
stringOptional-
优先返回某一种语言的文档，使用 ISO 639-1 代码；也接受 `zh-TW`、`pt-BR` 等地区形式。这是偏好而非严格过滤，因此仍可能出现其他语言的页面；搜索后端不支持的代码会被直接忽略，而不会导致搜索失败。该值会在 `search_metadata.lang` 中回显；省略时默认为 `en`。
Example: es
site
stringOptional-
限定为单个域名。会以 `site:<domain>` 追加到查询词后，效果与手动输入完全一致。
Example: docs.anthropic.com
safe_search
booleanOptional-
开启严格的安全搜索过滤。不设置时为关闭。
Example: true
time_range
stringOptional-
按时间范围限定：`day`、`week`、`month`、`year` 或 `all`。`all` 表示不加限制，同时也是默认值。
Example: week
file_type
stringOptional-
限定为单一文件扩展名。会以 `filetype:<ext>` 追加，因此 `pdf`、`xlsx`、`pptx` 都可用。
Example: pdf
redact_pii
boolean | objectOptionalfalse
在结果被存储或返回之前，从本次调用返回的文本中移除个人数据。 作用于搜索返回的标题与摘要；你发送的 `query` 原样回显，不做处理。 `true` 是 `{ mode: "fast" }` 的简写：四个正则类别全开，以标签替换。只要请求了脱敏，响应就会在 `data` 内带上 `redaction: { entities, count, mode }`，即使没有任何匹配（`count: 0`）也会带上，因此“什么都没找到”永远不会被误认为“参数被忽略了”；没有命中的类别会被省略，而不是报成 `0`。脱敏在结果存储**之前**执行，因此超出阈值、之后再用 [read_result](/docs/api-reference/tools/read-result) 读回的结果本身就已脱敏。两条刻意的边界：地址类字段（`url`、`link`、`href`、`canonical_url`）从不脱敏；由文本派生的计数（`content_length`、`word_count`、`character_count`）描述的是抽取时的文本，即脱敏之前的文本。
Example: true
max_inline_chars
numberOptional40000
内联返回的最大结果大小，以其 JSON 的字符数计（1,000-10,000,000）。超过后，响应会携带 `preview`（格式化 JSON 的前 `max_inline_chars` 个字符）、`result_handle`、`total_chars`、`truncated: true` 和 `expires_at`，其余部分由 [read_result](/docs/api-reference/tools/read-result) 读取，每次调用 1 credit。已存储的结果保留 1 小时。
Example: 40000

批量搜索

传 queries 而不是 query，即可在一次调用中运行最多 10 条搜索。每条查询都是与 query 调用相同的一次搜索——本 API 不做查询扩展、缓存、去重或重新排序——每条返回了结果的查询收取 5 credits。

terminalBash
curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "queries": [
      "mcp server for web scraping",
      "model context protocol tools"
    ],
    "limit": 10,
    "redact_pii": true
  }'

批量响应

results_by_query 是按你发送顺序排列的列表，一条查询对应一个条目，因此重复的查询会出现两次。失败的查询在其条目中带 error 而不是结果，并且不计费；无论如何调用都返回 200，包括所有查询都失败时，因此 credits_used 等于实际成功的条数乘以 5。单条 query 调用没有任何变化：其中不会出现 queries、count 或 results_by_query。

response.jsonJson
{
  "success": true,
  "data": {
    "queries": ["mcp server for web scraping", "model context protocol tools"],
    "count": 2,
    "results_by_query": [
      {
        "query": "mcp server for web scraping",
        "search_metadata": { "total_results": null, "results_returned": 10 },
        "results": [
          {
            "title": "CrawlForge MCP Server",
            "url": "https://www.crawlforge.dev/",
            "snippet": "Write to <EMAIL> for access."
          }
        ]
      },
      {
        "query": "model context protocol tools",
        "error": "Search request timeout"
      }
    ],
    "redaction": { "entities": { "EMAIL": 1 }, "count": 1, "mode": "fast" }
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 720
}

请求示例

terminalBash
curl -X POST https://crawlforge.dev/api/v1/tools/search_web \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "mcp server for web scraping",
    "limit": 10,
    "time_range": "month",
    "safe_search": true
  }'

响应示例

200 OK460ms
{
  "success": true,
  "data": {
    "query": "mcp server for web scraping",
    "search_metadata": {
      "total_results": null,
      "results_returned": 1,
      "offset": 0,
      "search_time": 0.312,
      "lang": "en",
      "safe_search": false,
      "time_range": "month",
      "site": null,
      "file_type": null
    },
    "results": [
      {
        "title": "CrawlForge MCP Server — 31 web tools for Claude",
        "url": "https://www.crawlforge.dev/",
        "snippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "displayLink": "www.crawlforge.dev",
        "formattedUrl": "https://www.crawlforge.dev/",
        "htmlSnippet": "Search, scrape, crawl and extract from any site through one MCP server.",
        "htmlTitle": "CrawlForge MCP Server — 31 web tools for Claude",
        "pagemap": {
          "cse_thumbnail": [
            {
              "src": "https://imgs.search.brave.com/example-thumbnail"
            }
          ],
          "metatags": [
            {
              "article:published_time": "2026-10-01T00:00:00"
            }
          ]
        }
      }
    ],
    "spelling_correction": null,
    "related_searches": []
  },
  "credits_used": 5,
  "credits_remaining": 995,
  "processing_time": 460
}
Field Descriptions
data.query实际搜索的查询，即你发送的原文，不含 `site` 和 `file_type` 运算符
data.search_metadata.total_results`null`：搜索后端不提供匹配总数。请用 `offset` 翻页，直到 `results_returned` 为 0
data.search_metadata.results_returned`results` 的长度——最多为 10
data.search_metadata.search_time上游搜索的耗时（秒），由 CrawlForge 测量。不是你这次请求的总延迟
data.results[].url目标链接。`formattedUrl` 携带同一地址
data.results[].htmlSnippet保留了搜索引擎 `<strong>` 关键词高亮的摘要片段。渲染前请先转义
data.results[].pagemap搜索引擎掌握时提供的页面信息：`cse_thumbnail[0].src`（缩略图 URL）和 `metatags[0]['article:published_time']`（页面发布时间）。两者都没有时省略该字段
data.spelling_correction搜索引擎改用纠正后的拼写进行搜索时，为纠正后的查询；否则为 `null`
data.related_searches始终为空数组：当前搜索后端不返回相关搜索。保留该字段是为了不破坏现有代码
credits_used每次搜索固定 5 credits，与你请求的 `limit` 无关

错误处理

查询无效（400 Bad Request）

VALIDATION_ERROR。query 为必填且不能为空。limit 超出 1-100、offset 为负数，或 time_range 不属于五个允许值之一，也返回同一状态码。同时传 query 和 queries、或两个都不传，返回同一个 400；queries 为空数组或超过 10 条、redact_pii 对象指定了本 API 无法脱敏的实体，或 redact_pii 带 mode: "model"（需要本 API 并不运行的 LLM），同样如此。

搜索失败（500 Internal Server Error）

TOOL_ERROR。涵盖上游搜索报错、搜索提供方的速率限制，以及 10 秒后超时。错误消息会指出具体原因。失败的搜索不计费。这是单条 query 的路径：一次失败的搜索与一直以来一样报错。queries 批次永远不会走到这里：失败的查询在它自己的 results_by_query 条目中报告，即使所有查询都失败，调用仍然返回 200。

credits 费用

5 credits
每次搜索 5 credits
一次搜索计一次费，无论返回 10 条还是 0 条。用 offset 翻页意味着又一次搜索，因此十页需要 50 credits。失败的搜索不计费。一次 search_web 调用按每条返回了结果的查询收取 5 credits：单条 query 收 5，queries 批次预估为 5 × 发送的查询条数，该值是上限：失败的查询不计费，因此一条都没成功的批次不产生任何费用。一次调用中的十条查询预估为 50，只有十条全部返回了结果才真的收 50。redact_pii 在默认的 fast 模式下不额外收费。

包含内容：

实时网页索引（Brave Search API），而不是缓存副本

标题、URL、摘要片段以及一份带高亮的摘要副本

搜索耗时，以及可用时的缩略图和页面发布时间

site、file_type、lang、time_range 与安全搜索过滤

搜索引擎应用了拼写纠正时返回纠正结果

计划推荐：

Free 计划： 1,000 个一次性试用 credits = 200 次搜索

Hobby 计划： 5,000 credits = 1,000 次搜索（$19/mo）

Professional 计划： 100,000 credits = 20,000 次搜索（$99/mo）

相关工具

serp_rank
某个域名在某个查询下的确切自然排名（5 credits）
reddit_search
搜索 Reddit，该站点会阻止直接抓取（5 credits）
deep_research
在一次调用中完成搜索、阅读与综合（10 credits）
batch_scrape
抓取搜索返回的 URL（每个 URL 5 credits）