Get a batch

GET /api/v1/forward/batches/{batch_id} Returns the full batch object, including the current task counters and, once terminal, the output file IDs. After Create Batch returns, poll this endpoint to observe resource pre-validation, queuing, execution, and terminal results. Tasks in validating have been persisted but have not entered the execution queue.

Headers

Header	Required	Description
`Authorization`	Yes	`Bearer <PAT or SAT>`

Path parameters

Parameter	Type	Required	Description
`batch_id`	string	Yes	Batch ID.

Example request

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

Example response

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
  }
}

Response fields

Field	Type	Description
`id`	string	Batch ID with prefix `batch_`.
`object`	string	Always `batch`.
`status`	string	Batch status.
`input_file_id`	string	Input JSONL file ID.
`output_file_id`	string	Result file ID for successful lines. Omitted before generation.
`error_file_id`	string	Result file ID for failed lines. Omitted when there are no failed lines.
`completion_window`	string	Completion window.
`ignore_idle_window`	boolean	Always returned. Whether the batch ignores the idle window. Historical batches and batches created without the field use `false`.
`queue_reason`	string	Optional snapshot of the current queue reason. May be returned only in `validating` or `queued`.
`created_at`	string	Creation time, RFC 3339.
`expires_at`	string	Expiration time.
`request_counts`	object	Aggregate task counters.
`usage`	object/null	Current aggregate usage for persisted subtasks. `null` when no valid usage is available. A non-terminal batch returns the current partial aggregate; a terminal batch returns the final aggregate.
`usage.total_credits`	number	Sum of the final or current CAS Session `total_credits` for all subtasks. The unit is CAS Credit, not tokens or currency. Explicit zero values are preserved.
`metadata`	object	Caller-supplied metadata.
`error_message`	string	Batch-level error description. Present only when `status` is `failed`.

Status and counters

The normal resource-related status sequence is:

validating → queued → processing → finalizing → completed

validating: synchronous JSONL structure checks and existing unattended-policy checks have completed; effective Template/Identity resources and file resources are being validated in the background. The Scheduler does not activate a Batch in this state.
queued: resource pre-validation has completed and at least one executable task exists; the Batch is waiting for the idle window and concurrency capacity.
processing: the Scheduler has passed the queued → processing gate, and only executable pending tasks enter the queue.
If every task fails pre-validation, the Batch moves directly from validating to finalizing without creating a Session.

request_counts is the current persisted snapshot and always satisfies:

total = pending + running + completed + failed + cancelled + expired

During validating, pending means accepted tasks still awaiting resource pre-validation; it does not mean that the tasks have been queued. When asynchronous pre-validation finds invalid resources, pending decreases and failed increases by the same amount, while total remains unchanged. A task-level resource failure does not set the whole Batch to failed. Failed tasks still appear in the output and error files. Only Batch-level errors, such as an unreadable input file, a persistence failure, or an unrecoverable resource-validation process, produce a Batch-level failed status and error_message.

Scheduling fields

owner is the business ownership scope associated with the credential: a PAT is scoped to the current user, while an administrator SAT is scoped to its organization and workspace. ignore_idle_window=true makes the Batch eligible outside the idle window; it does not mean immediate execution or higher priority. Per-owner mutual exclusion, global Batch capacity, global Task capacity, the validating → queued gate, and FIFO ordering still apply. Inside the idle window, regular Batches and Batches that ignore the window share FIFO order by created_at and ID; ignoring the window does not move a Batch ahead. completion_window still starts at created_at and includes validation, queueing, and execution time; it is not extended or reset. queue_reason is a dynamic read-time snapshot that may change immediately after the response. It is omitted if the snapshot cannot be loaded, without affecting a successful detail response. The first matching reason in the following priority order is returned:

Priority	Value	Meaning
1	`idle_window`	The current time is outside the idle window and this Batch does not ignore it.
2	`owner_processing`	Another Batch for the same owner is already `processing`.
3	`global_capacity`	The global number of `processing` Batches has reached capacity.
4	`scheduler_pending`	The Batch is `queued`, none of the first three conditions blocks it, and it is waiting for Scheduler activation.

In validating, only the first three confirmed external blockers can be returned. When none applies, the field is omitted; scheduler_pending is not returned. queue_reason is omitted for processing, finalizing, cancelling, expiring, and all terminal states. Reaching global capacity does not prevent Create Batch from returning validating; subsequent waiting can be represented by global_capacity.

Error codes

HTTP	Type	Code	Trigger
404	`not_found_error`	`batch_not_found`	Batch does not exist or belongs to another user.
401	`authentication_error`	`authentication_required`	PAT or SAT is invalid or expired.

Notes

Cross-user access returns 404 batch_not_found.
404 batch_not_found does not distinguish a nonexistent Batch from one that is invisible to the caller; clients must not infer resource ownership from it. A 404 during file-resource pre-validation is handled with the same safe config_error classification.
Clients should poll this endpoint to observe the batch reaching a terminal state (completed, failed, cancelled, or expired).

Headers

Path parameters

Example request

Example response

Response fields

Status and counters

Scheduling fields

Error codes

Notes

List batches

Get output file

​Headers

​Path parameters

​Example request

​Example response

​Response fields

​Status and counters

​Scheduling fields

​Error codes

​Notes

​Related

List batches

Get output file

Headers

Path parameters

Example request

Example response

Response fields

Status and counters

Scheduling fields

Error codes

Notes

Related