# 批量任务

[批量链接数据](/tools/batch-stats/) 把最多 2,000 条帖子或主页链接作为一个批量任务来读。链接只提交一次，任务在后台每次读 50 条，你凭句柄读取每一行。每一行按它所在平台的一次调用扣费；失效的链接和没跑到的行不扣。批量任务在购买积分后可用。

- 页面：https://socialtoai.com/zh/docs/batches/
- 最近更新：2026-10-25

- POST: `https://api.socialtoai.com/v1/tools/batch_stats`

输入和各平台的积分见文档里的[批量链接数据](https://socialtoai.com/zh/docs/tools/batch-stats.md)，这一页讲的是任务本身。

## 提交批量

- 先带 `confirm: false` 拿报价：这个任务最多扣多少，报价免费。批量在后台运行，所以不带 `confirm: true` 的请求也只返回报价。
- 再带 `confirm: true` 发一次，返回 HTTP 202 和一个 `handle`，这时还没扣费。带同一个 `Idempotency-Key` 再发同样的批量，返回的是同一个句柄。
- 需要买过积分的账户，以及打开了“发起批量”权限的 Key，否则返回 HTTP 403。只要有一条链接认不出平台，整个请求就以 `invalid_params` 拒绝，什么都不跑。

**cURL**

```
curl https://api.socialtoai.com/v1/tools/batch_stats \
  -H "Authorization: Bearer $SOCIALTOAI_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://x.com/NASA"],
    "confirm": true
  }'
```

**202 Accepted** (202, 0 积分)

```
{
  "request_id": "req_00000000-0000-4000-8000-000000000003",
  "schema_version": "v1",
  "status": "running",
  "handle": "res_00000000000040008000000000000003",
  "retry_after_seconds": 5,
  "billing": {
    "cost_credits": 0,
    "balance_credits": 100,
    "today_spend_credits": 0,
    "daily_limit_credits": null,
    "daily_remaining_credits": null,
    "display": "本次 0 积分，余额 100 积分（约 $0.33）"
  }
}
```

## 读取结果

用句柄读 `GET /v1/results/{handle}`，读多少次都免费。运行中返回 HTTP 202，带着目前已有的行和 `retry_after_seconds`；结束后返回 HTTP 200。加 `?format=csv` 导出成表格。任务结束后结果保存 24 小时。

**cURL**

```
curl https://api.socialtoai.com/v1/results/res_00000000000040008000000000000003 \
  -H "Authorization: Bearer $SOCIALTOAI_API_KEY"
```

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `request_id` | string | 发起这个任务的请求编号。 |
| `schema_version` | "v1" | 返回格式的版本。 |
| `tool` | "batch_stats" | 任务运行的工具。 |
| `status` | "running" \| "done" \| "stopped" \| "cancelled" \| "expired" \| "refused" | 先是 `running`，结束后是下面的终态之一。 |
| `stop_reason` | string \| null | 提前结束的原因：`too_many_failed_rows`、`deadline`，或某一波被拒绝时的错误代码。 |
| `handle` | string | 读取这个任务用的句柄。 |
| `retry_after_seconds` | integer | 运行中：多少秒后再读。（可能不出现） |
| `progress.rows` | integer | 提交的链接数。 |
| `progress.rows_done` | integer | 已经跑完的行数。 |
| `progress.waves` | integer | 任务切成的波数。 |
| `progress.waves_done` | integer | 已经跑完的波数。 |
| `charge.quote_credits` | integer | 报价：这个任务最多扣多少积分。 |
| `charge.charged_credits` | integer | 已跑的行到目前扣了多少积分。 |
| `main_number.id` | string | 任务的主要数字：`engagement_total`。 |
| `main_number.value` | number | 有效链接的互动合计。 |
| `result.ok` | integer | 成功返回的行。 |
| `result.dead` | integer | 失效的链接：已删除、私密或不存在。 |
| `result.failed` | integer | 没有拿到结果的行。 |
| `result.unrecognized` | integer | 从链接里读不出是哪条帖子或哪个账号的行。 |
| `result.not_run` | integer | 任务没跑到的行。 |
| `result.dead_links` | string[] | 失效的链接本身。 |
| `rows` | array | 每条链接一行，顺序同提交时，见下表。 |
| `expires_at` | string \| null | 结果可读到什么时候；运行中为 `null`。 |

每一行：

| 字段 | 类型 | 说明 |
| --- | --- | --- |
| `row` | integer | 它在 `urls` 里的位置，从 0 开始。 |
| `url` | string | 提交时的链接。 |
| `platform` | string | 链接所在的平台。 |
| `kind` | "post" \| "account" \| null | `post` 或 `account`；链接看不出时为 `null`。 |
| `status` | "ok" \| "dead" \| "failed" \| "unrecognized" \| "not_run" | 这一行的结果。只有 `ok` 扣费。 |
| `credits` | integer | 这一行扣的积分。 |
| `item` | object \| any \| null | 帖子或账号现在的样子，按[返回格式](https://socialtoai.com/zh/docs/api/response.md)。 |
| `extra` | array | 有的平台要再调一次才能拿到帖子的数字，那次调用的条目放在这里。 |

## 任务怎么结束

任务按每 50 行切成一波，一波接一波地跑。不论怎么结束，跑过的行照扣，其余的不扣。

| status | 含义 |
| --- | --- |
| `running` | 还在一波一波地跑。读取返回 HTTP 202，带着目前已有的行。 |
| `done` | 每一行都跑完了。 |
| `stopped` | 已跑的行里失败超过 30%，不再开新的一波：`stop_reason` 是 `too_many_failed_rows`。 |
| `cancelled` | 你在控制台取消了它。 |
| `expired` | 6 小时用完了：`stop_reason` 是 `deadline`。 |
| `refused` | 某一波没能开始，比如余额用完了：`stop_reason` 是对应的错误代码。 |

## 扣多少

- 每一行是它所在平台的一次调用，按这个平台帖子链接或主页链接的价格扣。拿到结果的行照扣，数字是 0 也一样。
- 失效的链接、读不出的链接和没跑到的行不扣。`charge.charged_credits` 不会超过报价。
- 批量不能暂停，可以在控制台的任务页取消，Key 发起的也一样：不再开新的一波，正在跑的那一波跑完并结算，没跑的行不扣。取消后不能撤回。
- 任务结束时，会向你的 [Webhook](https://socialtoai.com/zh/docs/webhooks.md) 发一条 `batch.finished`。

## 通过 MCP

你的 AI 用 `research` 工具运行它（`tool` 设为 `batch_stats`），再带着句柄调一次同一个工具来读结果。[工具列表](https://socialtoai.com/zh/docs/mcp/tools.md) 里有它拿到的描述。