查询 Batch 详情

根据 ID 获取 Batch 详情。

GET /api/v1/forward/batches/{batch_id}

返回完整 Batch 对象，包含当前任务计数聚合与输出文件 ID（终态后可用）。

​

请求头

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

​

路径参数

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

​

示例请求

curl -s -X GET 'https://api.qoder.com/api/v1/forward/batches/batch_completed001' \
  -H "Authorization: Bearer $QODER_PAT"

​

示例响应

HTTP 200 OK

{
  "id": "batch_completed001",
  "object": "batch",
  "status": "completed",
  "input_file_id": "file_input001",
  "output_file_id": "file_output001",
  "completion_window": "24h",
  "created_at": "2026-07-07T07:25:01Z",
  "expires_at": "2026-07-08T07:25:01Z",
  "request_counts": {
    "total": 30,
    "pending": 0,
    "running": 0,
    "completed": 30,
    "failed": 0,
    "cancelled": 0,
    "expired": 0
  },
  "usage": null
}

​

响应字段

字段	类型	说明
id	string	Batch ID，前缀 batch_。
object	string	固定为 batch。
status	string	Batch 状态。
input_file_id	string	输入 JSONL 文件 ID。
output_file_id	string	成功结果文件 ID；未完成或未生成时省略。
error_file_id	string	失败行结果文件 ID；无失败行时省略。
completion_window	string	完成窗口。
created_at	string	创建时间，RFC 3339。
expires_at	string	过期时间。
request_counts	object	任务计数聚合。
usage	object/null	预留字段，v1 固定为 null。
metadata	object	调用方业务元数据。
error_message	string	Batch 级错误描述；仅 failed 状态出现。

​

错误码

HTTP	Type	Code	触发条件
404	not_found_error	batch_not_found	Batch 不存在或跨用户访问。
401	authentication_error	authentication_required	PAT 无效或已过期。

​

注意事项

• 跨用户访问返回 404 batch_not_found。
• 客户端应通过轮询该接口感知 Batch 是否进入终态（completed / failed / cancelled / expired）。

​

相关

列出 Batches

获取输出文件