---
title: "Retrieve a batch"
method: GET
path: "/api/v1/batches/{batchId}"
tags: ["batches"]
---

# Retrieve a batch

`GET /api/v1/batches/{batchId}`

## Request

- Base URL: `https://api.trigger.dev`
- URL: `https://api.trigger.dev/api/v1/batches/{batchId}`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/docs/api/v1/batches/:batchId/get.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve a batch by its ID, including its status and the IDs of all runs in the batch.

## Response `200`

Successful request

- object
  - `id` string: The batch ID.
  - `status` 'PENDING' | 'PROCESSING' | 'COMPLETED' | 'PARTIAL_FAILED' | 'ABORTED': The current status of the batch.
  - `idempotencyKey` string, nullable: The idempotency key provided when triggering, if any.
  - `createdAt` string, date-time
  - `updatedAt` string, date-time
  - `runCount` integer: The total number of runs in the batch.
  - `runs` string[]: Array of run IDs in the batch.
  - `successfulRunCount` integer, nullable: Number of successful runs (populated after completion).
  - `failedRunCount` integer, nullable: Number of failed runs (populated after completion).
  - `errors` object[], nullable: Error details for failed items (present for PARTIAL_FAILED batches).
    - `index` integer: The index of the failed item.
    - `taskIdentifier` string: The task identifier of the failed item.
    - `error` object: The error details.
    - `errorCode` string, nullable: An optional error code.

## Other responses

- `401`: Unauthorized request
- `404`: Batch not found

## Changes

- **2026-02-24** `646fa10cb62e`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/changes/api/v1/batches/:batchId/get.md)

---

[API](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api.md) - [All operations](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/triggerdotdev/apis/trigger-dev-v3-rest-api/revisions/441161111493?raw)