批量任务
[批量链接数据](/tools/batch-stats/) 把最多 2,000 条帖子或主页链接作为一个批量任务来读。链接只提交一次，任务在后台每次读 50 条，你凭句柄读取每一行。每一行按它所在平台的一次调用扣费；失效的链接和没跑到的行不扣。批量任务在购买积分后可用。
POST
https://api.socialtoai.com/v1/tools/batch_stats输入和各平台的积分见文档里的批量链接数据，这一页讲的是任务本身。
提交批量
- 先带
confirm: false拿报价：这个任务最多扣多少，报价免费。批量在后台运行，所以不带confirm: true的请求也只返回报价。 - 再带
confirm: true发一次，返回 HTTP 202 和一个handle，这时还没扣费。带同一个Idempotency-Key再发同样的批量，返回的是同一个句柄。 - 需要买过积分的账户，以及打开了“发起批量”权限的 Key，否则返回 HTTP 403。只要有一条链接认不出平台，整个请求就以
invalid_params拒绝，什么都不跑。
curl https://api.socialtoai.com/v1/tools/batch_stats \ -H "Authorization: Bearer $SOCIALTOAI_KEY" \ -H "Idempotency-Key: $(uuidgen)" \ -H "Content-Type: application/json" \ -d '{ "urls": ["https://x.com/NASA"], "confirm": true }'{ "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 https://api.socialtoai.com/v1/results/res_00000000000040008000000000000003 \ -H "Authorization: Bearer $SOCIALTOAI_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 | 帖子或账号现在的样子，按返回格式。 |
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 发一条
batch.finished。
通过 MCP
你的 AI 用 research 工具运行它（tool 设为 batch_stats），再带着句柄调一次同一个工具来读结果。工具列表 里有它拿到的描述。
最近更新：