---
title: "List Message Batches."
method: GET
path: "/v1/messages/batches"
tags: ["Messages"]
---

# List Message Batches.

`GET /v1/messages/batches`

List all Message Batches with pagination.

## Query parameters

- `limit` integer — Maximum number of batches to return.
- `before_id` string, nullable — Return batches created before this batch ID.
- `after_id` string, nullable — Return batches created after this batch ID.

## Response `200`

Successful Response

- ListMessageBatchesResponse — Response from GET /v1/messages/batches.
  - `data` MessageBatch[], required — List of MessageBatch objects.
    - `id` string, required — Unique object identifier (msgbatch_ prefix).
    - `type` 'message_batch'
    - `processing_status` 'in_progress' | 'canceling' | 'ended', required — Processing status of the Message Batch.
    - `request_counts` MessageBatchRequestCounts — Tallies of requests by their status within a batch.
      - `processing` integer — Number of requests currently processing.
      - `succeeded` integer — Number of successfully completed requests.
      - `errored` integer — Number of requests that encountered an error.
      - `canceled` integer — Number of canceled requests.
      - `expired` integer — Number of expired requests.
    - `created_at` string, required — RFC 3339 datetime when the batch was created.
    - `expires_at` string, required — RFC 3339 datetime when processing will expire.
    - `cancel_initiated_at` string, nullable — RFC 3339 datetime when cancellation was initiated.
    - `ended_at` string, nullable — RFC 3339 datetime when all processing ended.
    - `archived_at` string, nullable — RFC 3339 datetime when the batch was archived.
    - `results_url` string, nullable — URL to a .jsonl file containing the results.
  - `has_more` boolean, required — Whether there are more results available.
  - `first_id` string, nullable — ID of the first batch in the list.
  - `last_id` string, nullable — ID of the last batch in the list.

## Other responses

- `400` — The request was invalid or malformed
- `429` — The client has sent too many requests in a given amount of time
- `500` — The server encountered an unexpected error
- `default` — An error occurred

---

[API](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis.md) · [All operations](https://skmtc.net/ogx-ai/apis/ogx-specification-stable-experimental-apis/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/ogx-ai/ogx-specification-stable-experimental-apis/revisions/f3f783962256/schema)