# List Batches

Once you have [processed a batch](/batch-labels) you’ll want to get the batch details, which will include batch status, a list of errors (if any), and linke to download the resources.

You can get batch details in the following ways:

- **List batches**: Get a list of batches that match your query parameters.
- **Get batch by id**: Get the details of a specific batch with its `batch_id`.
- **Get batch by external batch id**: Get the details of a specific batch with its `external_batch_id`.


## List by Query Parameters

The `GET /v2/batches` method will return a response with an array of batches that meet your request parameters. Each batch in the response array will include batch properties like status, errors, and URLs to download the resources associated with the batch (labels, forms, etc).

Since there's potential for the response to include a large number of batches, you can filter the results with query parameters.

| Query Parameter | Type | Description |
|  --- | --- | --- |
| `status` | *enumerated string* | `open`, `queued`, `completed`, `processing`, `archived`, `invalid`, `completed_with_errors` |
| `page` | *integer* | defaults to 1 |
| `page_size` | *integer* | defaults to 100 |
| `sort_dir` | *string* | `asc` or `desc` |
| `sort_by` | *string* | `ship_date`, `processed_at` |


### Sample Request & Response

**GET /v2/batches**


```http
GET /v2/batches?status=open HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
{
 "batches": [
   {
     "label_layout": null,
     "label_format": null,
     "batch_id": "se-1013790",
     "external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
     "batch_notes": "2024-7-25 Morning Shipments",
     "created_at": "2024-07-25T15:24:46.657Z",
     "errors": 0,
     "warnings": 0,
     "completed": 0,
     "forms": 0,
     "count": 1,
     "batch_shipments_url": {
       "href": "https://api.shipstation.com/v2/shipments?batch_id=se-1013790"
     },
     "batch_labels_url": {
       "href": "https://api.shipstation.com/v2/labels?batch_id=se-1013790"
     },
     "batch_errors_url": {
       "href": "https://api.shipstation.com/v2/batches/se-1013790/errors"
     },
     "label_download": {
       "href": "https://api.shipstation.com/v2/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf"
     },
     "form_download": {
       "href": "https://api.shipstation.com/v2/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf"
     },
     "status": "open"
   }
 ],
 "total": 1,
 "page": 1,
 "pages": 1,
 "links": {
   "first": {
     "href": "https://api.shipstation.com/v2/batches?status=open&page=1&page_size=100"
   },
   "last": {
     "href": "https://api.shipstation.com/v2/batches?status=open&page=1&page_size=100"
   },
   "prev": {},
   "next": {}
 }
}
```

## Get Batch By ID

Use this method to get the batch details of a specific `batch_id`.

### Requirements

- The `batch_id` for the batch you wish to get.


### Sample Request & Response

**GET /v2/batches/:batch_id**


```http
GET /v2/batches/se-1013790 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
{
 "label_layout": null,
 "label_format": null,
 "batch_id": "se-1013790",
 "external_batch_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
 "batch_notes": "2024-7-25 Morning Shipments",
 "created_at": "2024-07-25T15:24:46.657Z",
 "errors": 0,
 "warnings": 0,
 "completed": 0,
 "forms": 0,
 "count": 1,
 "batch_shipments_url": {
   "href": "https://api.shipstation.com/v2/shipments?batch_id=se-1013790"
 },
 "batch_labels_url": {
   "href": "https://api.shipstation.com/v2/labels?batch_id=se-1013790"
 },
 "batch_errors_url": {
   "href": "https://api.shipstation.com/v2/batches/se-1013790/errors"
 },
 "label_download": {
   "href": "https://api.shipstation.com/v2/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf"
 },
 "form_download": {
   "href": "https://api.shipstation.com/v2/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf"
 },
 "status": "open"
}
```

## Get Batch By External Batch ID

This method allows you to retrieve batch resources via the `external_batch_id` value if you provided one when [creating the batch](/batch-labels).

### Requirements

- The `external_batch_id` for the batch you wish to get.


### Sample Request & Response

**GET /v2/batches/external_batch_id/:external_batch_id**


```http
GET /v2/batches/external_batch_id/32cc2f34-5d9e-466c-8e3f-62c38ad9dc46 HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**

The response for this call will have the same result as the [get batch by id request](#get-batch-by-id).


```json
{
 "label_layout": null,
 "label_format": null,
 "batch_id": "se-1013790",
 "external_batch_id": "32cc2f34-5d9e-466c-8e3f-62c38ad9dc46",
 "batch_notes": "2024-7-25 Morning Shipments",
 "created_at": "2024-07-25T15:24:46.657Z",
 "errors": 0,
 "warnings": 0,
 "completed": 0,
 "forms": 0,
 "count": 1,
 "batch_shipments_url": {
   "href": "https://api.shipstation.com/v2/shipments?batch_id=se-1013790"
 },
 "batch_labels_url": {
   "href": "https://api.shipstation.com/v2/labels?batch_id=se-1013790"
 },
 "batch_errors_url": {
   "href": "https://api.shipstation.com/v2/batches/se-1013790/errors"
 },
 "label_download": {
   "href": "https://api.shipstation.com/v2/downloads/1/uths7PctKUqbM4OfmgzXLg/label-1013790.pdf"
 },
 "form_download": {
   "href": "https://api.shipstation.com/v2/downloads/1/xKVZeKA650-bvQB_oriYkQ/form-1013790.pdf"
 },
 "status": "open"
}
```

## Batch Error Handling

Errors in batches must be handled differently from synchronous requests. You must retrieve the status of your batch by [getting a batch](#get-batch-by-id) and getting an overview of the statuses or by [listing the batch errors](#list-batch-errors).

### Invalid or Completed with Errors

If the batch enters an *Invalid* or *Completed with Errors* state, you cannot re-use the batch.

1. [List the batch errors](#list-batch-errors) to extract the shipments and the reasons why they failed.
2. Correct the errors in the shipments by updating the shipment.
3. [Create a new batch](/batch-labels) for the shipments and rates in the invalid or error state.
4. [Process the new batch](/batch-labels).


### List Batch Errors

If any of your batches encounter an error when processing, you can use the List Batch Errors call to specifically list the errors that occurred on the batch.

### Example Request & Response

**GET /v2/batches/:batch_id/errors**


```http
GET /v2/batches/se-12345/errors HTTP/1.1
Host: api.shipstation.com
API-Key: __YOUR_API_KEY_HERE__
```

**Response**


```json
{
     "error": "Insufficient account balance",
     "shipment_id": "se-12345",
     "external_shipment_id": "TestId-1"
}
```