---
title: "Retrieve a Message Batch."
method: GET
path: "/v1/messages/batches/{message_batch_id}"
tags: ["Messages"]
---

# Retrieve a Message Batch.

`GET /v1/messages/batches/{message_batch_id}`

Retrieve the status of a Message Batch by its ID.

## Path parameters

- `message_batch_id` string, required

## Response `200`

Successful Response

- MessageBatch — A Message Batch object.
  - `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.

## 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/versions/f3f783962256/schema)