---
title: "Retrieve Batch"
method: GET
path: "/v1/messages/batches/{batch_id}"
tags: ["messages"]
---

# Retrieve Batch

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

Retrieve the status and details of a batch run.

## Path parameters

- `batch_id` string, required

## Response `200`

Successful Response

- BatchJob
  - `created_by_id` string, nullable — The id of the user that made this object.
  - `last_updated_by_id` string, nullable — The id of the user that made this object.
  - `created_at` string, date-time — The unix timestamp of when the job was created.
  - `updated_at` string, date-time, nullable — The timestamp when the object was last updated.
  - `status` 'created' | 'running' | 'completed' | 'failed' | 'pending' | 'cancelled' | 'expired' — Status of the job.
  - `completed_at` string, date-time, nullable — The unix timestamp of when the job was completed.
  - `stop_reason` 'end_turn' | 'error' | 'llm_api_error' | 'invalid_llm_response' | 'invalid_tool_call' | 'max_steps' | 'no_tool_call' | 'tool_rule' | 'cancelled' | 'requires_approval'
  - `metadata` object, nullable — The metadata of the job.
  - `job_type` 'job' | 'run' | 'batch'
  - `background` boolean, nullable — Whether the job was created in background mode.
  - `agent_id` string, nullable — The agent associated with this job/run.
  - `callback_url` string, nullable — If set, POST to this URL when the job completes.
  - `callback_sent_at` string, date-time, nullable — Timestamp when the callback was last attempted.
  - `callback_status_code` integer, nullable — HTTP status code returned by the callback endpoint.
  - `callback_error` string, nullable — Optional error message from attempting to POST the callback endpoint.
  - `ttft_ns` integer, nullable — Time to first token for a run in nanoseconds
  - `total_duration_ns` integer, nullable — Total run duration in nanoseconds
  - `id` string — The human-friendly ID of the Job

## Other responses

- `422` — Validation Error

## Changes

- **2025-09-18** `3a2d48137c08` — 2 info
  - added the optional property `agent_id` to the response with the `200` status
  - added the optional property `background` to the response with the `200` status

[Change history](https://skmtc.dev/yu-code666/apis/letta-api/changes/v1/messages/batches/:batch_id/get.md)

---

[API](https://skmtc.dev/yu-code666/apis/letta-api.md) · [All operations](https://skmtc.dev/yu-code666/apis/letta-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/yu-code666/letta-api/revisions/6cec99480c13/schema)