> ## Documentation Index
> Fetch the complete documentation index at: https://docs.querying.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 网站爬取转 Markdown API（WEB_CRAWL）

> 从起始地址爬取站点，以 Markdown 获取每个页面，按返回的页面数计费。

`WEB_CRAWL` 从起始地址按广度优先跟随站点的链接，并像 [`WEB_SCRAPE`](/zh/engines/web-scrape) 一样读取每个页面。一个结果中即可获得每个页面的 Markdown、元数据和图片。

| | |
| - | - |
| `taskType` | `WEB_CRAWL` |
| 输入 | `url`（必填）；`maxPages`、`maxDepth`、`maxChars`、`includePaths`、`excludePaths`、`includeSubdomains`、`country` |
| 积分 | 每返回一个页面 1 积分。提交时任务预留 `maxPages` 积分。 |
| 国家 | 默认 `US`。 |
| 位置 | 不支持（`422 LOCATION_UNSUPPORTED`）。 |

## 请求

```bash theme={"theme":"css-variables"}
curl -X POST https://api.querying.ai/v1/async/task \
  -H "Authorization: Bearer $QUERYING_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "taskType": "WEB_CRAWL", "payload": { "url": "https://www.example.com/docs", "maxPages": 25, "maxDepth": 2, "includePaths": ["/docs/**"] } }'
```

## 参数

| 字段 | 必填 | 说明 |
| - | - | - |
| `url` | 是 | 起始地址。规则与 `WEB_SCRAPE` 相同：公开的 `http` 或 `https`、默认端口、最长 2,048 个字符。无论路径模式和 `robots.txt` 如何规定，起始页始终会读取。 |
| `maxPages` | 否 | 要读取的页面数，包括起始页。1 到 100 的整数，默认 10。 |
| `maxDepth` | 否 | 从起始页跟随链接的次数，0 到 5 的整数，默认 2。`0` 表示只读起始页。 |
| `maxChars` | 否 | 每个页面 `markdown` 的上限，1,000 到 50,000 的整数，默认 20,000。 |
| `includePaths`、`excludePaths` | 否 | 路径模式，与 [`WEB_MAP`](/zh/engines/web-map) 相同：各最多 20 个，以 `/` 开头，最长 200 个字符。`*` 在一个路径段内匹配，`**` 跨多个路径段匹配。`excludePaths` 优先。 |
| `includeSubdomains` | 否 | 设为 `true` 时跟随指向站点子域名的链接，默认 `false`。 |
| `country` | 否 | 请求页面时使用的地区，默认 `US`。 |

爬取只跟随满足以下条件的链接：留在同一站点（带不带 `www.` 均可），匹配路径模式，指向网页而非文件（跳过 PDF、图片、压缩包等文件），并且站点 `robots.txt` 允许所有爬虫访问。

## 响应

例如：

```json theme={"theme":"css-variables"}
{
  "url": "https://www.example.com/docs",
  "pages": [
    {
      "url": "https://www.example.com/docs",
      "finalUrl": "https://www.example.com/docs",
      "depth": 0,
      "statusCode": 200,
      "title": "...",
      "markdown": "# ...",
      "images": [],
      "truncated": false
    }
  ],
  "failed": [{ "url": "https://www.example.com/docs/old", "depth": 1, "error": "the site answered 404 for this page" }],
  "stopReason": "max-pages"
}
```

| 字段 | 说明 |
| - | - |
| `pages` | 读取到的页面，按爬取发现的顺序排列。每个页面包含 `WEB_SCRAPE` 的字段以及 `depth`（从起始页跟随链接的次数）。 |
| `failed` | 无法读取的页面，各带 `url`、`depth`，以及作为 `error` 的站点回应原因。 |
| `stopReason` | 爬取结束的原因，见下表。 |

| `stopReason` | 含义 |
| - | - |
| `done` | 没有剩余可跟随的链接。 |
| `max-pages` | 已读取 `maxPages` 个页面。 |
| `failures` | 连续 10 个页面无法读取，或失败页面总数达到 `maxPages`。 |
| `time` | 爬取时间用尽。约 4 分钟后不再开始读取新页面。 |

## 积分

提交时，任务按 `maxPages` 每页预留 1 积分（上例为 25 积分）。完成时，按 `pages` 中的每个页面扣 1 积分，其余预留积分释放。`failed` 中的页面不收费。25 个页面中返回 3 个的爬取花费 3 积分。预留机制见[积分与限制](/zh/concepts/credits-and-limits.md)。

## 限制与错误

* 起始页无法读取时，任务以 `PAGE_UNAVAILABLE` 失败。其他无法读取的页面记入 `failed`，爬取继续进行。
* 无效选项返回 `422 VALIDATION_ERROR`，并指出相应字段。
* `WEB_CRAWL` 忽略 `markdown`、`rawResponse` 和 `searchQueries`。它以 `422` 拒绝 `html` 和 `analysis`，以 `400` 拒绝 `citationAnalysis`；见[不支持的标志](/zh/engines/response-options.md#不支持的标志)。
* 其他请求错误见[错误](/zh/concepts/errors.md)。

## 相关内容

* [网站地图](/zh/engines/web-map.md)：列出站点地址而不读取内容
* [网页抓取](/zh/engines/web-scrape.md)：读取单个页面


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.