列出 Batches

GET /api/v1/forward/batches 返回当前鉴权凭据所属 owner 创建的 Batch 列表，按创建时间倒序排列。

请求头

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

查询参数

参数	类型	是否必填	默认值	说明
status	string	否	-	按状态过滤。
limit	integer	否	20	分页大小，最大 100。
after_id	string	否	-	向后翻页游标。
before_id	string	否	-	向前翻页游标。

示例请求

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

示例响应

HTTP 200 OK

{
  "object": "list",
  "data": [
    {
      "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": 48.25
      }
    },
    {
      "id": "batch_queued001",
      "object": "batch",
      "status": "queued",
      "input_file_id": "file_input002",
      "completion_window": "24h",
      "ignore_idle_window": true,
      "queue_reason": "owner_processing",
      "created_at": "2026-07-06T11:59:02Z",
      "expires_at": "2026-07-07T11:59:02Z",
      "request_counts": {
        "total": 50,
        "pending": 50,
        "running": 0,
        "completed": 0,
        "failed": 0,
        "cancelled": 0,
        "expired": 0
      },
      "usage": null
    }
  ],
  "has_more": true,
  "first_id": "batch_completed001",
  "last_id": "batch_queued001"
}

响应字段

字段	类型	说明
object	string	固定为 `list`。
data	array	当前页的 Batch 对象。
first_id	string	当前页第一条记录 ID。
last_id	string	当前页最后一条记录 ID。
has_more	boolean	是否还有更多记录。

data 中每个 Batch 对象都始终返回 ignore_idle_window boolean；历史数据和创建时省略该字段的 Batch 均为 false。queue_reason 是可选 string，只在 validating 或 queued 时可能出现。

调度字段

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 是整页 Batch 共享同一读取时调度状态的动态快照，不是持久化状态，可能在响应后立即变化。快照加载失败时会省略，不影响列表接口成功。取值按以下优先级判定，命中第一个即返回：

优先级	值	含义
1	`idle_window`	当前不在闲时窗口，且 Batch 未设置无视窗口。
2	`owner_processing`	同 owner 已有其他 `processing` Batch。
3	`global_capacity`	全局 `processing` Batch 数已达容量上限。
4	`scheduler_pending`	Batch 已是 `queued`，前三类都未阻塞，正等待 Scheduler 激活。

validating 只返回前三类已确定的外部阻塞；没有外部阻塞时省略，不返回 scheduler_pending。processing、finalizing、cancelling、expiring 和所有终态均省略 queue_reason。全局容量已满不会阻止创建 Batch 成功返回 validating，后续等待可通过 global_capacity 表达。

错误

HTTP	Type	Code	触发条件
400	`invalid_request_error`	`invalid_pagination`	分页参数不合法。
401	`authentication_error`	`authentication_required`	PAT 或 SAT 无效或已过期。

备注

has_more=true 时用 last_id 作为 after_id 继续翻页。
output_file_id / error_file_id 在终态生成后才出现。
error_message 仅 failed 状态出现。
usage 与 Batch 详情口径一致：至少一个子任务已有合法 CAS Session 用量时返回 total_credits 当前汇总，否则为 null。该值单位为 CAS Credit，不代表 token 数或货币金额。
只返回当前 owner 创建的 Batch；PAT 按当前用户隔离，管理员 SAT 按 organization + workspace 隔离。

请求头

查询参数

示例请求

示例响应

响应字段

调度字段

错误

备注

相关

创建 Batch

查询 Batch 详情

​请求头

​查询参数

​示例请求

​示例响应

​响应字段

​调度字段

​错误

​备注

​相关

创建 Batch

查询 Batch 详情

请求头

查询参数

示例请求

示例响应

响应字段

调度字段

错误

备注

相关