爬取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

起始 URL 的参数名是 start_url，不是 url。所有参数均使用 snake_case——未知键会被静默丢弃而不是报错，因此像 maxDepth 这样的驼峰命名键会被忽略并回退到默认值。

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

请求以 CrawlForge 产品令牌标识自身，并默认遵守 robots.txt。每个来源的规则在每次爬取中获取一次并缓存。被禁止的 URL 会被跳过且不占用 max_pages 配额；若 start_url 本身被禁止，则在抓取任何内容之前返回 403——因此被拦截的爬取不消耗 credits。

爬取行为说明

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

广度优先，而非深度优先

深度 1 的所有页面都会先于任何深度 2 的页面被访问。max_pages 较小时，得到的是一张宽而浅的地图，而不是某一条深分支。

失败的页面被静默跳过

若某个页面超时或返回错误，它会被排除在 pages 之外，爬取继续进行。pages_crawled 可能小于 max_pages，且不会指明哪些 URL 失败了。

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_crawled": 12,
    "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
      }
    ],
    "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_crawled实际访问并解析的页面数。当有页面失败或站点已无可达链接时，会小于 max_pages。

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)

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

如何控制成本与耗时： max_pages 是真正起作用的杠杆。它直接限制工作量；又因为 timeout 会在这些页面之间均分，较高的 max_pages 配上较低的 timeout 会让每个页面时间极其紧张，并悄悄推高失败页面的数量。

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 方案： 50,000 credits/月 = 12,500 次爬取（$99/月）

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

crawl_deep

使用场景

绘制文档站点地图

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

在批量抓取前构建 URL 列表

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

审计站内链接结构

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

检查内容实际埋得有多深

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

Endpoint

POST/api/v1/tools/crawl_deep

Auth Required

Free 方案 1 次请求/秒

4 credits

Parameters

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

爬取行为说明

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

广度优先，而非深度优先

深度 1 的所有页面都会先于任何深度 2 的页面被访问。max_pages 较小时，得到的是一张宽而浅的地图，而不是某一条深分支。

失败的页面被静默跳过

若某个页面超时或返回错误，它会被排除在 pages 之外，爬取继续进行。pages_crawled 可能小于 max_pages，且不会指明哪些 URL 失败了。

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_crawled": 12,
    "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
      }
    ],
    "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_crawled实际访问并解析的页面数。当有页面失败或站点已无可达链接时，会小于 max_pages。

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)

爬取失败 (500 TOOL_ERROR)

爬取过程中发生意外故障。单个页面失败不会导致该错误——它们会被静默跳过——因此出现 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 方案： 50,000 credits/月 = 12,500 次爬取（$99/月）

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

crawl_deep

使用场景

Endpoint

Parameters

爬取行为说明

请求示例

响应示例

错误处理

credits 消耗

相关工具

crawl_deep

使用场景

Endpoint

Parameters

爬取行为说明

请求示例

响应示例

错误处理

credits 消耗

相关工具