API 参考 / research

取消采集批次（平台超管）

POST /api/v1/research/ingest-batches/{batchId}/cancel · cancelResearchIngestBatch

取消一个非终态批次（queued/running 推进 canceled）。调度器在抓取循环检查 ctx，及时退出。 已终态（succeeded/partial/failed/canceled）返回 409。仅平台超管可访问。

本接口要求浏览器会话。Bearer API Token 无法调用——Token 的生命周期管理必须在网页端完成。

参数

batchId（必填）

string

响应字段 · 200

id（必填）

string

week（必填）

string —— ISO 8601 周编号，如 2026-W32

source（必填）

string

status（必填）

enum；取值：queued / running / succeeded / partial / failed / canceled

counts（必填）

ResearchIngestBatchCounts

counts.discovered（必填）

integer —— Discover 返回的记录总数

counts.fetched（必填）

integer —— Fetch 成功的记录数

counts.persisted（必填）

integer —— 去凭据 + content hash 幂等后实际写入对象存储的记录数

counts.failed（必填）

integer —— Fetch 失败的记录数（按分类）

errorSummary

string —— 失败摘要（哪些 id 失败、什么分类），partial/failed 时非空

snapshotRef

string —— 原始快照的 blobstore key 前缀引用

triggeredBy（必填）

enum；取值：schedule / rerun / manual

createdAt（必填）

string

startedAt

string

finishedAt

string

updatedAt（必填）

string

错误

• 401：Problem 错误响应
• 403：Problem 错误响应
• 404：Problem 错误响应
• 409：Problem 错误响应

请求示例（curl）

curl -X POST "https://你的项目.workflow.games/api/v1/research/ingest-batches/{batchId}/cancel" \
  -H "Authorization: Bearer wfp_…"

响应示例

HTTP/1.1 200
{
  "id": "018f3c2e-0000-7000-8000-000000000000",
  "week": "示例文本",
  "source": "示例文本",
  "status": "queued",
  "counts": {
    "discovered": 1,
    "fetched": 1,
    "persisted": 1,
    "failed": 1
  },
  "triggeredBy": "schedule",
  "createdAt": "示例文本",
  "updatedAt": "2026-08-01"
}

合同真值：OpenAPI 3.1（0.1.0）。

相关：Agent 接入指南 · 使用指南 · API 参考索引