# List Labels

To get a list of labels you've [created](/apis/shipengine/docs/labels/create-a-label) in ShipStation API, you make a GET call to the **/v1/labels** endpoint.

By default, this endpoint returns all labels, 25 at a time, starting with those most recently created.

You can optionally use query parameters to filter the results as well as control their sort order and the number of results returned at a time.

## Query Parameters

| Query Parameter | Type | Description |
|  --- | --- | --- |
| `label_status` | *enumerated string* | Only return labels that are currently in the specified status.  ex: `processing`, `completed`, `error`, `voided` |
| `carrier_id` | *string* | Only return labels for a specific [carrier account](/apis/shipengine/docs/carriers/setup)  ex: `se-28529731` |
| `service_code` | *string* | Only return labels for a specific [carrier service](/apis/shipengine/docs/reference/list-carrier-services)  ex: `usps_first_class_mail` |
| `tracking_number` | *string* | Only return labels with a specific tracking number  ex: `1Z5615280351136446` |
| `batch_id` | *string* | Only return labels that were created in a specific [batch](/apis/shipengine/docs/labels/bulk)  ex: `se-28529731` |
| `warehouse_id` | *string* | Only return labels that originate from a specific [warehouse](/apis/shipengine/docs/shipping/ship-from-a-warehouse)  ex: `se-28529731` |
| `created_at_start` | *date string* | Only return labels that were created on or after a specific date/time Uses [ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601), ex: `2019-07-25T15:24:46.657Z` |
| `created_at_end` | *date string* | Only return labels that were created on or before a specific date/time Uses [ISO 8601 Standard](https://en.wikipedia.org/wiki/ISO_8601), ex: `2019-07-25T15:24:46.657Z` |
| `page` | *integer* | Return a specific "page" of results. Defaults to the first page. If set to a number that's greater than the number of pages of results, an empty page will be returned.  ex. `100` |
| `page_size` | *integer* | The number of labels to return per response. Defaults to 25.  ex. `100` |
| `sort_dir` | *enumerated string* | Controls the sort order of the query. See **Extended Description** for more details.   `asc` or `desc` (defaults to `desc`). |
| `sort_by` | *enumerated string* | Controls which property the query is sorted by. Defaults to `created_at`  `modified_at`, `created_at` |


### Extended Description: `sort_dir`

* The `sort_dir` property determines which part of the data, oldest or newest, will be returned, not the order of the shipments in the response. The data is always from oldest to newest.
* Page size behavior:
  * When the `page_size` is set to 100 and fewer than 100 shipments are created, no change will be visible in the returned data. The data will be from oldest to newest.
  * When the `page_size` is set to 5, in the case of `asc`, the system will return the five oldest shipments sorted from oldest to newest. While in the case of `desc`, the system will return the five most recently created shipments, sorted from oldest to newest.


## Example Request & Response

The following example demonstrates how to query for the most recently completed label.

The `label_status` parameter limits the results to completed labels. Setting the `page_size` parameter to `1` ensures that only the most recent label will be returned since the default sort order is `created_at` `desc`.


```http
GET /v1/labels?label_status=completed&page_size=1 HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Cache-Control: no-cache
```

**Response**


```json
{
  "labels": [
    {
      "label_id": "se-421357",
      "status": "completed",
      "shipment_id": "se-2129025",
      "ship_date": "2019-07-25T05:00:00.000Z",
      "created_at": "2019-07-25T15:24:46.657Z",
      "shipment_cost": {
        "currency": "usd",
        "amount": 18.49
      },
      "insurance_cost": {
        "currency": "usd",
        "amount": 0.0
      },
      "rate_details": [
        {
          "rate_detail_type": "shipping",
          "carrier_description": null,
          "carrier_billing_code": "Base Rate",
          "carrier_memo": null,
          "amount": {
            "currency": "usd",
            "amount": 18.49
          },
          "billing_source": "Carrier"
        }
      ],
      "tracking_number": "1Z28A1R91201009738",
      "is_return_label": false,
      "is_international": false,
      "batch_id": "",
      "carrier_id": "se-123890",
      "service_code": "ups_3_day_select",
      "package_code": "package",
      "voided": false,
      "voided_at": null,
      "label_format": "pdf",
      "label_layout": "4x6",
      "trackable": false,
      "carrier_code": "ups",
      "tracking_status": "unknown",
      "label_download": {
        "pdf": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf",
        "png": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.png",
        "zpl": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.zpl",
        "href": "https://api.shipengine.com/v1/downloads/1/s_Tqsu9euEKub6Acc_9UIg/testlabel-2128732.pdf"
      },
      "form_download": null,
      "insurance_claim": null
    }
  ],
  "total": 3820,
  "page": 1,
  "pages": 3820,
  "links": {
    "first": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=1&page_size=1"
    },
    "last": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=3820&page_size=1"
    },
    "prev": {},
    "next": {
      "href": "https://api.shipengine.com/v1/labels?label_status=completed&page=2&page_size=1"
    }
  }
}
```