查询 Batch 子任务

GET /api/v1/forward/batches/{batch_id}/tasks 分页查询 Batch 内逐条任务的状态、结果摘要、错误、制品和用量。Batch 处于任意状态时均可调用。只返回当前 PAT 用户所属 Batch 的子任务。

请求头

Header	是否必填	说明
Authorization	是	`Bearer <PAT>`

路径参数

参数	类型	是否必填	说明
batch_id	string	是	Batch ID。

查询参数

参数	类型	是否必填	默认值	说明
status	string	否	-	按任务状态过滤：`pending`、`running`、`completed`、`failed`、`cancelled`、`expired`。
custom_id	string	否	-	按调用方任务标识精确过滤，仅支持单值；未命中返回空列表。
limit	integer	否	20	分页大小，最大 100。
after_id	string	否	-	向后翻页游标，传上一页响应的 `last_id`；游标必须属于当前 Batch。

示例请求

curl -s -X GET 'https://api.qoder.com.cn/api/v1/forward/batches/batch_completed001/tasks?limit=20' \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

示例响应

HTTP 200 OK

{
  "object": "list",
  "data": [
    {
      "custom_id": "task-001",
      "status": "completed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:03:41Z",
      "output_summary": "report generated",
      "usage": {
        "total_credits": 2.75
      },
      "artifacts": [
        {
          "file_id": "file_abc",
          "name": "report.xlsx",
          "size": 20480,
          "content_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet"
        }
      ]
    },
    {
      "custom_id": "task-002",
      "status": "failed",
      "started_at": "2026-08-06T14:01:03Z",
      "completed_at": "2026-08-06T14:01:20Z",
      "error": {
        "code": "session_error",
        "message": "sandbox terminated unexpectedly"
      },
      "usage": {
        "total_credits": 0.5
      },
      "artifacts": []
    }
  ],
  "has_more": true,
  "first_id": "task-001",
  "last_id": "task-002"
}

响应字段

字段	类型	说明
object	string	固定为 `list`。
data	array	当前页的 Batch Task 对象。
data[].custom_id	string	调用方任务标识，也是当前版本的公开分页游标。
data[].status	string	任务状态，与 Batch `request_counts` 明细状态口径一致。
data[].started_at	string	最终一次持久化执行尝试的开始时间，RFC 3339 UTC；未开始时省略。
data[].completed_at	string	任务完成时间，RFC 3339 UTC；未完成时省略。
data[].output_summary	string	最终回复文本，最多 500 个 Unicode 字符；无结果时省略。
data[].error	object	仅 `failed` 任务返回，包含 `code` 和 `message`。
data[].artifacts	array	已交付制品；无制品时返回空数组。
data[].usage	object	最终或当前 CAS Session 的用量；CAS 未返回合法用量时省略。
data[].usage.total_credits	number	CAS Session 累计 Credit 消耗；不代表 token 数或货币金额，显式零值保留。
first_id	string	当前页第一条任务的 `custom_id`。
last_id	string	当前页最后一条任务的 `custom_id`。
has_more	boolean	是否还有更多任务。

瞬时错误重试会为任务创建新 CAS Session，因此 usage 只表示最终或当前 Session，不累加已被替换的历史 Session。

错误码

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_request`	`status`、`limit` 或 `after_id` 不合法。
404	`not_found_error`	`batch_not_found`	Batch 不存在、跨用户访问，或结果文件已完成 30 天清理。
401	`authentication_error`	`authentication_required`	PAT 无效或已过期。

注意事项

has_more=true 时，将 last_id 原样作为下一次请求的 after_id。
制品下载复用 Files API，不新增 Batch 专用制品下载端点。

查询 Batch 子任务

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

错误码

注意事项

相关

查询 Batch 详情

获取输出文件

​请求头

​路径参数

​查询参数

​示例请求

​示例响应

​响应字段

​错误码

​注意事项

​相关

查询 Batch 详情

获取输出文件

请求头

路径参数

查询参数

示例请求

示例响应

响应字段

错误码

注意事项

相关