> ## Documentation Index
> Fetch the complete documentation index at: https://docs.qoder.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a batch

> Retrieve a batch by ID.

`GET /api/v1/forward/batches/{batch_id}`

Returns the full batch object, including the current task counters and, once terminal, the output file IDs.

## Headers

| Header          | Required | Description    |
| --------------- | -------- | -------------- |
| `Authorization` | Yes      | `Bearer <PAT>` |

## Path parameters

| Parameter  | Type   | Required | Description |
| ---------- | ------ | -------- | ----------- |
| `batch_id` | string | Yes      | Batch ID.   |

## Example request

```bash theme={null}
curl -s -X GET 'https://api.qoder.com/api/v1/forward/batches/batch_completed001' \
  -H "Authorization: Bearer $QODER_PAT"
```

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "id": "batch_completed001",
  "object": "batch",
  "status": "completed",
  "input_file_id": "file_input001",
  "output_file_id": "file_output001",
  "completion_window": "24h",
  "created_at": "2026-07-07T07:25:01Z",
  "expires_at": "2026-07-08T07:25:01Z",
  "request_counts": {
    "total": 30,
    "pending": 0,
    "running": 0,
    "completed": 30,
    "failed": 0,
    "cancelled": 0,
    "expired": 0
  },
  "usage": null
}
```

## Response fields

| Field               | Type        | Description                                                              |
| ------------------- | ----------- | ------------------------------------------------------------------------ |
| `id`                | string      | Batch ID with prefix `batch_`.                                           |
| `object`            | string      | Always `batch`.                                                          |
| `status`            | string      | Batch status.                                                            |
| `input_file_id`     | string      | Input JSONL file ID.                                                     |
| `output_file_id`    | string      | Result file ID for successful lines. Omitted before generation.          |
| `error_file_id`     | string      | Result file ID for failed lines. Omitted when there are no failed lines. |
| `completion_window` | string      | Completion window.                                                       |
| `created_at`        | string      | Creation time, RFC 3339.                                                 |
| `expires_at`        | string      | Expiration time.                                                         |
| `request_counts`    | object      | Aggregate task counters.                                                 |
| `usage`             | object/null | Reserved field, always `null` in v1.                                     |
| `metadata`          | object      | Caller-supplied metadata.                                                |
| `error_message`     | string      | Batch-level error description. Present only when `status` is `failed`.   |

## Error codes

| HTTP | Type                   | Code                      | Trigger                                          |
| ---- | ---------------------- | ------------------------- | ------------------------------------------------ |
| 404  | `not_found_error`      | `batch_not_found`         | Batch does not exist or belongs to another user. |
| 401  | `authentication_error` | `authentication_required` | PAT is invalid or expired.                       |

## Notes

* Cross-user access returns `404 batch_not_found`.
* Clients should poll this endpoint to observe the batch reaching a terminal state (`completed`, `failed`, `cancelled`, or `expired`).

## Related

<CardGroup cols={2}>
  <Card title="List batches" icon="list" href="/cloud-agents/api/forward/batches/list" />

  <Card title="Get output file" icon="download" href="/cloud-agents/api/forward/batches/get-output" />
</CardGroup>