現在のユーザーのバッチをページング付きで一覧します。
GET /api/v1/forward/batches
現在の認証情報に対応する owner が作成した Batch を、作成時刻の降順で返します。
Headers
| Header | Required | Description |
|---|---|---|
Authorization | Yes | Bearer <PAT または SAT> |
Query parameters
| Parameter | Type | Required | Default | Description |
|---|---|---|---|---|
status | string | No | - | ステータスでフィルタします。 |
limit | integer | No | 20 | ページサイズ。最大 100。 |
after_id | string | No | - | 次ページへのカーソル。 |
before_id | string | No | - | 前ページへのカーソル。 |
Example request
Example response
HTTP 200 OK
Response fields
| Field | Type | Description |
|---|---|---|
object | string | 常に list。 |
data | array | 現在ページのバッチオブジェクト。 |
first_id | string | 現在ページの先頭レコード ID。 |
last_id | string | 現在ページの末尾レコード ID。 |
has_more | boolean | 追加レコードがあるかどうか。 |
data 内の各 Batch オブジェクトは常に ignore_idle_window を boolean で返します。過去の Batch、および作成時にこのフィールドを省略した Batch では false です。queue_reason は任意の string で、validating または queued の場合にのみ返ることがあります。
スケジューリングフィールド
owner は認証情報に対応するビジネス上の所有範囲です。PAT は現在のユーザー単位、管理者 SAT は organization と workspace の組み合わせで判定されます。
ignore_idle_window=true は Batch をアイドルウィンドウ外でも実行対象にしますが、即時実行や高い優先度を意味しません。同一 owner の排他制御、グローバル Batch 容量、グローバル Task 容量、validating → queued ゲート、FIFO 順序は引き続き適用されます。アイドルウィンドウ内では、通常の Batch とウィンドウを無視する Batch が created_at と ID に基づく同じ FIFO 順序を共有し、ウィンドウを無視しても順番は繰り上がりません。completion_window は引き続き created_at から起算され、検証、キュー待ち、実行の時間を含みます。延長やリセットはされません。
一覧内の queue_reason は、ページ全体で同じ読み取り時点のスケジューリング状態を使用する動的スナップショットです。永続化された状態ではなく、レスポンス直後に変わる可能性があります。スナップショットの読み込みに失敗した場合は省略されますが、一覧 API の成功には影響しません。次の優先順で最初に一致した理由が返されます。
| 優先度 | 値 | 意味 |
|---|---|---|
| 1 | idle_window | 現在がアイドルウィンドウ外で、この Batch がウィンドウを無視する設定ではありません。 |
| 2 | owner_processing | 同じ owner の別の Batch がすでに processing です。 |
| 3 | global_capacity | グローバルの processing Batch 数が容量上限に達しています。 |
| 4 | scheduler_pending | Batch は queued で、最初の 3 条件には該当せず、Scheduler の起動を待っています。 |
validating では、最初の 3 つの確定済み外部ブロッカーだけが返ります。該当しない場合は省略され、scheduler_pending は返りません。processing、finalizing、cancelling、expiring、すべての終端状態では queue_reason が省略されます。グローバル容量が上限に達していても Create Batch は validating を返せます。その後の待機理由は global_capacity で表されます。
Error codes
| HTTP | Type | Code | Trigger |
|---|---|---|---|
| 400 | invalid_request_error | invalid_pagination | ページングパラメータが不正です。 |
| 401 | authentication_error | authentication_required | PAT または SAT が無効、もしくは期限切れです。 |
Notes
has_more=trueの場合はlast_idをafter_idに渡して次ページを取得します。output_file_id/error_file_idは終端状態到達後にのみ返されます。error_messageはfailedの場合のみ返されます。usageは Batch 詳細と同じ定義です。少なくとも 1 つのサブタスクに有効な CAS Session 使用量がある場合は現在のtotal_credits集計を返し、それ以外はnullです。単位は CAS Credit であり、token 数や金額ではありません。- 現在の owner が作成した Batch のみ返されます。PAT は現在のユーザー単位、管理者 SAT は organization と workspace の組み合わせで分離されます。