跳到正文
CrawlForge MCP
爬取4 credits

crawl_deep

从起始 URL 向外以广度优先方式遍历站点，沿链接抓取，直到达到您设定的页数或深度上限。返回抓取到的每个页面，包含标题、相对起点的深度，以及在该页发现的链接数量。

使用场景

绘制文档站点地图

从文档根目录开始，发现所有可达页面，深度值可直观反映信息的层级嵌套关系。

在批量抓取前构建 URL 列表

先爬取以发现 URL，再交给 batch_scrape 提取内容——比边爬取边做完整提取更省成本。

审计站内链接结构

每页链接数与深度分布可以看出哪些板块链接充分，哪些近乎孤立。

检查内容实际埋得有多深

pages_per_depth 能揭示重要页面是否距离入口有三到四次点击之远。

Endpoint

POST/api/v1/tools/crawl_deep
Auth Required
Free 方案 1 次请求/秒
4 credits

Parameters

NameTypeRequiredDefaultDescription
start_url
stringRequired-
爬取的起始 URL。必填。
Example: https://example.com/docs
max_pages
numberOptional10
最多访问的页面数，1-100。达到该数量后爬取立即停止，因此它同时限制了成本和耗时。
Example: 25
max_depth
numberOptional3
相对 `start_url` 的最大链接深度，1-5。起始页为深度 0。
Example: 2
same_domain_only
booleanOptionaltrue
为 true 时，只跟进主机名与 `start_url` 相同的链接。外部链接仍计入链接总数，但永远不会被访问。
Example: true
respect_robots_txt
booleanOptionaltrue
为 true 时，每个来源的 robots.txt 在每次爬取中获取一次，并跳过其中对 `CrawlForge` 禁止访问的所有 URL。缺失或无法访问的 robots.txt 视为没有任何限制。它是 `respect_robots` 的旧别名；两个名称设置的是同一项。
Example: true
respect_robots
booleanOptionaltrue
遵守每个来源的 robots.txt。这是规范名称，与 CrawlForge MCP 服务器共用；`respect_robots_txt` 是旧别名，仍然可用——两者设置其一即可。保持 `true` 时，被禁止的 `start_url` 会在抓取之前以 403 拒绝，爬取过程中被禁止的页面会被跳过。仅在您与该站点另有约定时才设为 `false`——此时响应会带上一条 `warnings`，并且该覆盖会记录到您的 API key 上。
Example: true
crawl_delay
numberOptional1000
两次页面抓取之间的等待毫秒数，0-5000。从第二个页面开始生效。对小型站点或有速率限制的站点应调高该值。
Example: 1000
timeout
numberOptional30000
整次爬取的总时间预算（毫秒），1000-60000，会按 `max_pages` 均分给每次抓取作为各自的超时。因此调高 `max_pages` 会缩短单个页面被允许的时间。
Example: 30000
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
redact_pii
boolean | objectOptionalfalse
在结果被存储或返回之前，从本次调用返回的文本中移除个人数据。 作用于爬取返回的每一个页面。 `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

爬取行为说明

在解读返回数字之前，这几点值得先了解。

广度优先，而非深度优先
深度 1 的所有页面都会先于任何深度 2 的页面被访问。max_pages 较小时，得到的是一张宽而浅的地图，而不是某一条深分支。
失败的页面列在 errors 中
若某个页面超时、无法访问或返回 HTTP 错误，它会被排除在 pages 之外，连同其 URL、深度和原因列入 errors，爬取继续进行。每个失败页面仍会占用 max_pages 预算中的一页，因此 pages_attempted 等于 pages_crawled 加 error_count。
links 是数量，不是列表
pages 中的每一项报告的是在该页找到的可跟进链接数量。若需要链接 URL 本身，请对具体页面使用 extract_links。
不执行 JavaScript
页面通过 HTTP 抓取并按原始 HTML 解析，因此客户端渲染出的链接不可见，其对应页面也永远不会被发现。

请求示例

terminalBash
# The starting URL parameter is start_url, not url.
curl -X POST https://crawlforge.dev/api/v1/tools/crawl_deep \
  -H "X-API-Key: cf_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "start_url": "https://example.com/docs",
    "max_pages": 25,
    "max_depth": 2,
    "same_domain_only": true,
    "crawl_delay": 1000,
    "timeout": 30000
  }'

响应示例

200 OK8,420ms
{
  "success": true,
  "data": {
    "start_url": "https://example.com/docs",
    "pages_attempted": 13,
    "pages_crawled": 12,
    "error_count": 1,
    "max_depth_reached": 2,
    "total_links_found": 184,
    "pages": [
      {
        "url": "https://example.com/docs",
        "depth": 0,
        "title": "Documentation",
        "links": 24
      },
      {
        "url": "https://example.com/docs/quickstart",
        "depth": 1,
        "title": "Quickstart",
        "links": 18
      },
      {
        "url": "https://example.com/docs/api",
        "depth": 1,
        "title": "API Reference",
        "links": 31
      }
    ],
    "errors": [
      {
        "url": "https://example.com/docs/legacy",
        "depth": 2,
        "error": "HTTP 404"
      }
    ],
    "crawl_stats": {
      "completed": true,
      "duration_ms": 8380,
      "pages_per_depth": {
        "0": 1,
        "1": 6,
        "2": 5
      }
    }
  },
  "credits_used": 4,
  "credits_remaining": 996,
  "processing_time": 8420
}
Field Descriptions
data.pages_attempted爬取请求过的 URL 数：pages_crawled 加 error_count。
data.pages_crawled已获取并解析的页面数，每个在 pages 中占一条。当有页面失败或站点已无可达链接时，会小于 max_pages。
data.error_count已请求但未得到页面的 URL 数，每个在 errors 中占一条。
data.errors每个失败的 URL 一条记录：url、depth、error（原因，例如 "HTTP 404"），以及已知时的 code，例如 FETCH_TIMEOUT 或 FETCH_FAILED。
data.max_depth_reached实际到达的最深层级。小于 max_depth 说明爬取已穷尽站点，或先达到了 max_pages。
data.total_links_found各页链接数之和。跨页面的重复链接会被重复计入，因此并非去重后的 URL 数量。
data.pages每个已访问页面一条记录，按访问顺序排列——广度优先，先是深度 0，然后是全部深度 1。
data.pages.links该页找到的可跟进链接数量，而非 URL 本身。需要列表请使用 extract_links。
data.crawl_stats.duration_ms爬取所花费的时间，单位毫秒。略低于外层的 processing_time，后者还包含请求处理开销。
data.crawl_stats.pages_per_depth每个深度各访问了多少页面——即从 start_url 出发所看到的站点形态。
processing_time本次爬取的总实际耗时，单位毫秒。

错误处理

start_url 缺失或无效 (400 VALIDATION_ERROR)

最常见的原因是传了 url 而不是 start_url。未知键会被丢弃，于是请求到达时根本没有起始 URL。响应中的 details 数组会指出出错的字段。

参数超出范围 (400 VALIDATION_ERROR)

max_pages 须为 1-100，max_depth 为 1-5，crawl_delay 为 0-5000，timeout 为 1000-60000。超出范围的值会被直接拒绝，而不是截断到边界。

start_url 被 robots.txt 禁止 (403 ROBOTS_DISALLOWED)

目标站点的 robots.txt 对该 URL 禁止了 CrawlForge。不会抓取任何内容，也不扣除 credits。仅在您与该站点另有约定时，才设置 respect_robots: false（或其旧别名 respect_robots_txt）——该覆盖会记录到您的 API key 上。该覆盖不适用于列入 CrawlForge 永久排除名单的主机——无论 respect_robots 取何值，这类主机一律被拒绝。

爬取失败 (500 TOOL_ERROR)

爬取过程中发生意外故障。单个页面失败不会导致该错误——它们会列入 errors——因此出现 500 意味着爬取本身无法继续。

credits 消耗

4 credits
每次请求 4 credits
每次调用固定 4 credits，与爬取访问了多少页面无关——爬 100 个页面和爬 5 个页面费用相同。失败的调用不计费。

成本明细：

任意爬取，1 至 100 个页面：4 credits

方案建议：

Free 方案： 1,000 个一次性试用 credits = 250 次爬取

Hobby 方案： 5,000 credits/月 = 1,250 次爬取（$19/月）

Professional 方案： 100,000 credits/月 = 25,000 次爬取（$99/月）

由于费用固定，对同一站点应优先使用一次高 max_pages 的爬取，而不是多次小规模爬取。

相关工具

map_site
无需访问每个页面即可发现 URL（2 credits）
extract_links
获取某个页面上真实的链接 URL（1 credit）
batch_scrape
从爬取发现的 URL 中提取内容（每个 URL 5 credits）
scrape
对单个页面进行完整内容提取（2 credits）