---
title: "List batches"
method: GET
path: "/batches"
tags: ["batches"]
---

# List batches

`GET /batches`

Returns a paginated list of your batches, newest first.

Use cursor-based pagination: pass `last_id` from the response as the `after` parameter to fetch the next page.

## Query parameters

- `pagination` object, required — Cursor-based pagination parameters for OpenAI-compatible endpoints. Used by batch and files APIs following OpenAI's pagination pattern: - `after`: Cursor ID to start after (exclusive) - `limit`: Maximum items to return (default: 20, max: 100)
  - `after` string, nullable — A cursor for use in pagination. `after` is an object ID that defines your place in the list.
  - `limit` integer, nullable — Maximum number of items to return (default: 20, max: 100)
- `search` string, nullable
- `include` string, nullable
- `member_id` string, uuid, nullable
- `status` string, nullable
- `created_after` string, date-time, nullable
- `created_before` string, date-time, nullable
- `active_first` boolean
- `completion_window` string, nullable

## Response `200`

List of batches. Check `has_more` to determine if additional pages exist.

- BatchListResponse — Response for batch list
  - `data` BatchResponse[], required
    - `analytics` BatchAnalytics — Aggregated analytics metrics for batch requests
      - `avg_duration_ms` number, double, nullable — Average request duration in milliseconds
      - `avg_ttfb_ms` number, double, nullable — Average time to first byte in milliseconds
      - `total_completion_tokens` integer, required — Total completion tokens across all requests
      - `total_cost` string, nullable — Total BILLED cost in credits (if pricing is available) — what the batch actually cost after prompt-cache discounts, matching the credits ledger / transactions page. (Until 2026-07 this field erroneously reported the un-discounted list price; see `total_list_cost` for that figure.)
      - `total_list_cost` string, nullable — Un-discounted list price of the same requests (no prompt-cache discounts applied). `total_list_cost - total_cost` = what caching saved on this batch. Additive field — clients that don't know it simply ignore it.
      - `total_prompt_tokens` integer, required — Total prompt tokens across all requests
      - `total_reasoning_tokens` integer, nullable — Total reasoning tokens across all requests
      - `total_requests` integer, required — Total number of requests with analytics data
      - `total_tokens` integer, required — Total tokens (prompt + completion) across all requests
    - `cancelled_at` integer, nullable
    - `cancelling_at` integer, nullable
    - `completed_at` integer, nullable
    - `completion_window` string, required — The requested processing window, or `"background"` for no-SLA spare-capacity processing.
    - `created_at` integer, required
    - `dwext` BatchDwExtResponse — Doubleword extension fields on batch responses. Returned as `"dwext": { ... }` at the top level of batch objects. Only present when there is Doubleword-specific data to surface.
      - `source` string, nullable — How the batch was created: "api", "frontend", or "sync".
      - `source_file` string, nullable — Original external file key (when source = "sync").
      - `source_id` string, nullable — Source connection ID (when source = "sync").
      - `source_name` string, nullable — Name of the source connection (when source = "sync").
      - `sync_id` string, nullable — Sync operation ID that created this batch (when source = "sync").
    - `endpoint` string, required
    - `error_file_id` string, nullable
    - `errors` BatchErrors — Batch-level errors
      - `data` BatchError[], required — Array of error details
        - `code` string, nullable — An error code identifying the error type
        - `line` integer, nullable — The line number of the input file where the error occurred, if applicable
        - `message` string, required — A human-readable message providing more details about the error
        - `param` string, nullable — The name of the parameter that caused the error, if applicable
    - `expired_at` integer, nullable
    - `expires_at` integer, nullable
    - `failed_at` integer, nullable
    - `finalizing_at` integer, nullable
    - `id` string, required
    - `in_progress_at` integer, nullable
    - `input_file_id` string, required
    - `metadata` object, nullable
    - `model` string, nullable — Model alias used by this batch's requests, or `"mixed"` when the input file spans multiple models. Cached on the batch at creation time; absent on batches created before this field existed.
    - `object` 'batch', required — Object type - always "batch"
    - `output_file_id` string, nullable
    - `request_counts` RequestCounts, required — Request counts for a batch
      - `completed` integer, required
      - `failed` integer, required
      - `total` integer, required
    - `status` string, required
  - `first_id` string, nullable
  - `has_more` boolean, required
  - `last_id` string, nullable
  - `object` 'list', required — Object type for lists - always "list"

## Other responses

- `500` — An unexpected error occurred. Retry the request or contact support if the issue persists.

---

[API](https://skmtc.dev/doubleword/apis/doubleword-api.md) · [All operations](https://skmtc.dev/doubleword/apis/doubleword-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/doubleword/doubleword-api/revisions/6617202865d8/schema)