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

# Firecrawl Data Sources

> 通过 CLI、MCP 或 API 使用 Firecrawl 的检索、URL 发现和页面抓取能力。

Firecrawl 提供 5 个独立 Endpoint。选择 Endpoint 后,Glasser 按该 Endpoint 执行;
这些调用不经过 Web Research Solution 的自动路由。

| 能力 | Endpoint | Price | 返回 |
| - | - | - | - |
| Scrape | `/v2/scrape` | \$0.001 / call | 单页 Markdown、HTML、原始 HTML |
| Search | `/v2/search` | \$0.0002 / result | Web、News、Images 结果列表 |
| Map | `/v2/map` | \$0.001 / call | 网站 URL 列表,不抓正文 |
| Crawl | `/v2/crawl` | \$0.001 / page | 自动发现并抓取网站页面 |
| Batch Scrape | `/v2/batch/scrape` | \$0.001 / page | 抓取已知 URL 列表 |

价格与参数以当次 `inspect` 返回的契约为准。Search 不包含结果页正文抓取。
Map 返回有效空列表也按次收费。这里不提供 Firecrawl Agent。

> [!WARNING]
>
> Crawl 和 Batch Scrape 每次最多 500 页,开始前需要 $2.50 的可用余额用于 Hold。
>   当前 Hold 不随输入页数缩小。实际按返回页数计 Charge,500 页最多 $0.50;
> 结算后释放未使用的 Hold。$2.50 不是最低消费。Search 的最高 Hold 为 $0.06。

## 先检查契约

```bash theme={null}
glasser search "Firecrawl batch scrape known URLs" --use-case "Fetch a list of public pages"
glasser inspect -p firecrawl -e /v2/batch/scrape
```

`inspect` 返回输入 Schema、Price、Endpoint version、运行方式和示例。
CLI 输出末尾的 `Run it` 命令包含此次检查的版本号。

## Search:检索与时间过滤

```bash theme={null}
glasser run -p firecrawl -e /v2/search --endpoint-version 1 \
  --idempotency-key research-search-001 --json \
  -i '{"query":"web research tools","limit":10,"sources":["web","news"],"tbs":"qdr:w","country":"US"}'
```

`query`、`limit` 和 `sources` 必填。`sources` 可选 `web`、`news`、`images`;
每个 source 最多 100 条。Charge 按 `data.web`、`data.news`、`data.images`
的实际结果条数之和计算。

`tbs` 使用 Firecrawl 原生时间过滤:例如 `qdr:w` 表示最近一周,
`cdr:1,cd_min:10/01/2026,cd_max:10/12/2026` 指定日期范围。
Search 不支持本接入之外的 `scrapeOptions` 或付费附加提取。

## Map:列出网站 URL

```bash theme={null}
glasser run -p firecrawl -e /v2/map --endpoint-version 1 \
  --idempotency-key research-map-001 --json \
  -i '{"url":"https://example.com","limit":100,"sitemap":"include","includeSubdomains":false}'
```

`url` 和 `limit` 必填。结果位于 `output.links`。Map 不返回页面正文。

## Crawl:发现并抓取页面

```bash theme={null}
glasser run -p firecrawl -e /v2/crawl --endpoint-version 1 \
  --idempotency-key research-crawl-001 --wait --wait-timeout 120 --json \
  -o crawl-output.json \
  -i '{"url":"https://example.com","limit":20,"allowExternalLinks":false,"maxDiscoveryDepth":2,"scrapeOptions":{"formats":["markdown","html","rawHtml"],"onlyMainContent":true,"parsers":[],"storeInCache":false,"maxAge":0}}'
```

`limit` 必填,范围为 1–500。`allowExternalLinks` 必须为 `false`。
抓取选项放在 `scrapeOptions` 中。

## Batch Scrape:抓取已知 URL

```bash theme={null}
glasser run -p firecrawl -e /v2/batch/scrape --endpoint-version 1 \
  --idempotency-key research-batch-001 --wait --wait-timeout 120 --json \
  -o batch-output.json \
  -i '{"urls":["https://example.com"],"formats":["markdown","html","rawHtml"],"onlyMainContent":true,"parsers":[],"storeInCache":false,"ignoreInvalidURLs":false,"maxAge":0}'
```

`urls` 必须包含 1–500 个 URL。抓取选项位于顶层。Crawl 和 Batch Scrape 支持同次
返回 `markdown`、`html`、`rawHtml`;`parsers: []`、`storeInCache: false` 必填。
`maxAge` 以毫秒指定可接受的已有缓存年龄,`0` 请求重新抓取。
不提供 AI formats、PDF 分页解析、browser actions 或 enrichment。
直接输入 X/Twitter、t.co 和 LinkedIn URL 会被拒绝。

## 异步等待与部分失败

Crawl 和 Batch Scrape 是异步 Run。`--wait` 等待同一个 Run,不会重新提交抓取。
CLI 等待时间到期后,保存 Run ID 并继续查询;不要创建新的 Run 来查询进度。

```bash theme={null}
glasser runs get -r <RUN_ID> --wait --wait-timeout 120 --json
glasser runs stop -r <RUN_ID>
```

`--wait-timeout` 只控制客户端等待时间。取消需要通过 `runs stop` 提交。
服务端 Job deadline 为 15 分钟;存在受理或结算歧义时另有 15 分钟调查期。
这两项独立 Endpoint 不使用 Fetch Solution 的 30 秒总预算。

Run 的 `status: "COMPLETED"` 表示交付和结算完成,不保证所有页面成功。
同时检查 `output.status`、`output.errors`、`output.robotsBlocked` 和每页的
`metadata.statusCode`。Provider 部分失败时,已抓取的页面仍可能正常交付并计 Charge:

```json theme={null}
{
  "status": "COMPLETED",
  "charge_usd": "0.001",
  "output": {
    "status": "failed",
    "total": 2,
    "completed": 1,
    "data": [{"markdown":"Public page","html":"<p>Public page</p>","rawHtml":"<html><body>Public page</body></html>"}],
    "errors": [{"url":"https://example.com/missing","error":"page unavailable"}],
    "robotsBlocked": []
  }
}
```

`--json` 输出完整 Run;`-o` 文件只保存 `output`。原生抓取结果没有经过 Fetch
Solution 的正文质量判断。重试同一笔调用时复用相同的 `idempotency_key` 和输入。

## API 与 MCP

API 使用 [Create Run](/docs/api-reference/runs/create),传入 `provider: "firecrawl"`、
所选 `endpoint` 和上面的 `input`。不需要新增 Glasser HTTP 路径。

MCP 使用现有的 `search`、`inspect`、`run`、`runs_get`、`runs_stop`。
例如 `run` 的 arguments 为:

```json theme={null}
{
  "provider": "firecrawl",
  "endpoint": "/v2/map",
  "endpoint_version": 1,
  "idempotency_key": "research-map-001",
  "input": {"url":"https://example.com","limit":100}
}
```

MCP 通过 `runs_get` 的 `run_id` 继续查询。需要自动选择 Provider、正文质量判断
和串行兜底时,使用 [Web Research Solution](/docs/api-reference/solutions/overview)。
Fetch 的默认策略仍为 Serper → Firecrawl,总预算仍为 30 秒。


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