Skip to main content
Batches

查询 Batch 详情

GET /api/v1/forward/batches/{batch_id} 返回完整 Batch 对象，包含当前任务计数聚合与输出文件 ID（终态后可用）。 创建 Batch 返回后可轮询此接口观察资源预校验、排队、执行和终态结果。validating 阶段的任务已经落库，但尚未进入执行队列。

请求头

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

路径参数

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

示例请求

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

示例响应

HTTP 200 OK 
{
  "id": "batch_completed001",
  "object": "batch",
  "status": "completed",
  "input_file_id": "file_input001",
  "output_file_id": "file_output001",
  "completion_window": "24h",
  "ignore_idle_window": false,
  "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": {
    "total_credits": 5.28
  }
}

响应字段

字段类型说明
idstringBatch ID，前缀 batch_。
objectstring固定为 batch。
statusstringBatch 状态。
input_file_idstring输入 JSONL 文件 ID。
output_file_idstring成功结果文件 ID；未完成或未生成时省略。
error_file_idstring失败行结果文件 ID；无失败行时省略。
completion_windowstring完成窗口。
ignore_idle_windowboolean始终返回。是否无视闲时窗口；历史数据和创建时省略该字段的 Batch 均为 false。
queue_reasonstring可选的动态排队原因快照；只在 validating 或 queued 时可能返回。
created_atstring创建时间，RFC 3339。
expires_atstring过期时间。
request_countsobject任务计数聚合。
usageobject/null已持久化子任务用量的当前汇总；没有合法用量时为 null。非终态 Batch 返回当前部分汇总，终态 Batch 返回最终汇总。
usage.total_creditsnumber各子任务最终或当前 CAS Session 的 total_credits 之和；单位为 CAS Credit，不代表 token 数或货币金额，显式零值保留。
metadataobject调用方业务元数据。
error_messagestringBatch 级错误描述；仅 failed 状态出现。

状态与计数

资源相关的正常状态链为： 
validating → queued → processing → finalizing → completed
  • validating：同步 JSONL 结构和既有无人值守策略检查已经完成，后台正在校验 Template/Identity 有效资源及文件资源。Scheduler 不会激活此状态的 Batch。
  • queued：资源预校验已完成，存在可执行任务，正在等待闲时窗口和并发额度。
  • processing：Scheduler 已通过 queued → processing 门禁，可执行的 pending 任务才会进入队列。
  • 若预校验后所有任务均失败，则从 validating 直接进入 finalizing，不会创建 Session。
request_counts 是当前持久化快照，并始终满足： 
total = pending + running + completed + failed + cancelled + expired
在 validating 阶段，pending 表示已接受但仍在等待资源预校验的任务，并不表示任务已经入队。异步预校验发现无效资源后，pending 会减少、failed 会等量增加，total 不变。 任务级资源失败不会使整个 Batch 进入 failed。失败任务仍会出现在 output/error 文件中；只有输入文件无法读取、持久化失败或资源校验流程本身无法恢复等 Batch 级错误才会产生 Batch 的 failed 状态和 error_message。

调度字段

owner 表示鉴权凭据对应的业务归属范围：PAT 按当前用户判定，管理员 SAT 按其 organization + workspace 判定。 ignore_idle_window=true 只让 Batch 不受闲时窗口限制，不代表立即执行或更高优先级。同 owner 互斥、全局 Batch 容量、全局 Task 容量、validating → queued 门禁和 FIFO 顺序仍然生效。闲时窗口内，两类 Batch 按 created_at / ID 共享 FIFO，无视窗口不会提前。completion_window 仍从 created_at 起算，校验、排队和执行时间均计入，不会被延长或重置。 queue_reason 是读取时的动态快照，可能在响应后立即变化；快照加载失败时会省略，不影响详情接口成功。取值按以下优先级判定，命中第一个即返回：
优先级值含义
1idle_window当前不在闲时窗口，且 Batch 未设置无视窗口。
2owner_processing同 owner 已有其他 processing Batch。
3global_capacity全局 processing Batch 数已达容量上限。
4scheduler_pendingBatch 已是 queued，前三类都未阻塞，正等待 Scheduler 激活。
validating 只返回前三类已确定的外部阻塞；没有外部阻塞时省略，不返回 scheduler_pending。processing、finalizing、cancelling、expiring 和所有终态均省略 queue_reason。全局容量已满不会阻止 创建 Batch 成功返回 validating，后续等待可通过 global_capacity 表达。

错误

HTTPTypeCode触发条件
404not_found_errorbatch_not_foundBatch 不存在或跨用户访问。
401authentication_errorauthentication_requiredPAT 或 SAT 无效或已过期。

备注

  • 跨用户访问返回 404 batch_not_found。
  • 404 batch_not_found 不区分 Batch 不存在和当前调用方不可见，客户端不应据此推断资源所有权。文件资源预校验中的 404 同样按安全的 config_error 处理。
  • 客户端应通过轮询该接口感知 Batch 是否进入终态（completed / failed / cancelled / expired）。

相关

列出 Batches

获取输出文件

快速入门
构建 Agent
配置 Agent 环境
委派任务给 Agent
集成 Agent
管理 Agent 上下文
账户
最佳实践
公告
API 参考