Skip to main content
Batches

List batches

List the current user's batches with pagination.

GET /api/v1/forward/batches Returns the Batches created by the owner associated with the current credential, sorted by creation time in descending order.

Headers

HeaderRequiredDescription
AuthorizationYesBearer <PAT or SAT>

Query parameters

ParameterTypeRequiredDefaultDescription
statusstringNo-Filter by status.
limitintegerNo20Page size. Maximum 100.
after_idstringNo-Cursor for forward pagination.
before_idstringNo-Cursor for backward pagination.

Example request

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

Example response

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

Response fields

FieldTypeDescription
objectstringAlways list.
dataarrayBatch objects on the current page.
first_idstringID of the first record on the page.
last_idstringID of the last record on the page.
has_morebooleanWhether more records are available.
Every Batch object in data always returns ignore_idle_window as a boolean. Historical Batches and Batches created without the field use false. queue_reason is an optional string that may appear only in validating or queued.

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. For the entire page, queue_reason is a dynamic snapshot based on the same scheduling state at read time. It is not persisted and may change immediately after the response. If the snapshot cannot be loaded, the field is omitted without affecting a successful list response. The first matching reason in the following priority order is returned:
PriorityValueMeaning
1idle_windowThe current time is outside the idle window and this Batch does not ignore it.
2owner_processingAnother Batch for the same owner is already processing.
3global_capacityThe global number of processing Batches has reached capacity.
4scheduler_pendingThe 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

HTTPTypeCodeTrigger
400invalid_request_errorinvalid_paginationPagination parameters are invalid.
401authentication_errorauthentication_requiredPAT or SAT is invalid or expired.

Notes

  • When has_more=true, use last_id as after_id to continue paging.
  • output_file_id and error_file_id only appear after a terminal state is reached.
  • error_message only appears when status is failed.
  • usage follows the same definition as batch details. It returns the current aggregate total_credits after at least one subtask has valid CAS Session usage; otherwise it is null. The unit is CAS Credit, not tokens or currency.
  • Only Batches created by the current owner are returned. PATs are isolated by current user; administrator SATs are isolated by organization and workspace.

Create a batch

Get a batch

First steps
Define your agent
Configure agent environment
Delegate work to your agent
Agent integrations
Manage agent context
Account
Best Practices
Announcements
API reference