> ## 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.

# List batches

> List the current user's batches with pagination.

`GET /api/v1/forward/batches`

Returns the batches created by the current PAT user, sorted by creation time in descending order.

## Headers

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

## Query parameters

| Parameter   | Type    | Required | Default | Description                     |
| ----------- | ------- | -------- | ------- | ------------------------------- |
| `status`    | string  | No       | -       | Filter by status.               |
| `limit`     | integer | No       | 20      | Page size. Maximum 100.         |
| `after_id`  | string  | No       | -       | Cursor for forward pagination.  |
| `before_id` | string  | No       | -       | Cursor for backward pagination. |

## Example request

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

## Example response

**HTTP 200 OK**

```json theme={null}
{
  "object": "list",
  "data": [
    {
      "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
    },
    {
      "id": "batch_processing001",
      "object": "batch",
      "status": "processing",
      "input_file_id": "file_input002",
      "completion_window": "24h",
      "created_at": "2026-07-06T11:59:02Z",
      "expires_at": "2026-07-07T11:59:02Z",
      "request_counts": {
        "total": 50,
        "pending": 20,
        "running": 5,
        "completed": 25,
        "failed": 0,
        "cancelled": 0,
        "expired": 0
      },
      "usage": null
    }
  ],
  "has_more": true,
  "first_id": "batch_completed001",
  "last_id": "batch_processing001"
}
```

## Response fields

| Field      | Type    | Description                         |
| ---------- | ------- | ----------------------------------- |
| `object`   | string  | Always `list`.                      |
| `data`     | array   | Batch objects on the current page.  |
| `first_id` | string  | ID of the first record on the page. |
| `last_id`  | string  | ID of the last record on the page.  |
| `has_more` | boolean | Whether more records are available. |

## Error codes

| HTTP | Type                    | Code                      | Trigger                            |
| ---- | ----------------------- | ------------------------- | ---------------------------------- |
| 400  | `invalid_request_error` | `invalid_pagination`      | Pagination parameters are invalid. |
| 401  | `authentication_error`  | `authentication_required` | PAT is invalid or expired.         |

## Notes

* When `has_more=true`, use `last_id` as `after_id` to continue paging.
* `output_file_id` and `error_file_id` only appear after a terminal state is reached.
* `error_message` only appears when `status` is `failed`.
* Only batches created by the current PAT user are returned.

## Related

<CardGroup cols={2}>
  <Card title="Create a batch" icon="plus" href="/cloud-agents/api/forward/batches/create" />

  <Card title="Get a batch" icon="file-text" href="/cloud-agents/api/forward/batches/get" />
</CardGroup>