---
title: "List labels"
method: GET
path: "/v1/labels"
tags: ["labels"]
---

# List labels

`GET /v1/labels`

This endpoint returns a list of labels that you've [created](https://www.shipengine.com/docs/labels/create-a-label/). You can optionally filter the results as well as control their sort order and the number of results returned at a time.

By default, all labels are returned, 25 at a time, starting with the most recently created ones.  You can combine multiple filter options to narrow-down the results.  For example, if you only want to get your UPS labels for your east coast warehouse you could query by both `warehouse_id` and `carrier_id`

## Query parameters

- `label_status` 'processing' | 'completed' | 'error' | 'voided' — The possible statuses that a [shipping label](https://www.shipengine.com/docs/labels/create-a-label/) can be in. |Status |Description |:------------|:----------------------------------------------------- |`processing` |When labels are created in a [batch](https://www.shipengine.com/docs/labels/bulk/), it may take a few minutes for all of the labels in the batch to be created. During this period, they will be in `processing` status. |`completed` |The label was successfully created |`error` |The label could not be created due to an error, such as an invalid delivery address |`voided` |The label has been [voided](https://www.shipengine.com/docs/labels/voiding/)
- `service_code` string — A [carrier service](https://www.shipengine.com/docs/shipping/use-a-carrier-service/), such as `fedex_ground`, `usps_first_class_mail`, `flat_rate_envelope`, etc.
- `carrier_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `tracking_number` string
- `batch_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `rate_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `shipment_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `warehouse_id` string — A string that uniquely identifies a ShipEngine resource, such as a carrier, label, shipment, etc.
- `created_at_start` string, date-time
- `created_at_end` string, date-time
- `refund_status` string[]
- `page` integer
- `page_size` integer
- `sort_dir` 'asc' | 'desc' — Controls the sort order of queries |Value |Description |:---------|:----------------------------------------------------- |`asc` |Return results in ascending order |`desc` |Return results in descending order
- `sort_by` 'modified_at' | 'created_at' | 'voided_at'

## Response `200`

The response includes a `labels` array containing a page of results (as determined by the `page_size` query parameter).  It also includes other useful information, such as the total number of labels that match the query criteria, the number of pages of results, and the URLs of the first, last, next, and previous pages of results.

- ListLabelsResponseBody — Many ShipEngine endpoints return a paged list of items. In addition to the returned items, these responses also include information about the total number of items, the number of pages of results, and URLs of other pages of results.
  - `total` integer, required — The total number of items across all pages of results
  - `page` integer, required — The current page number of results. For example, if there are 80 results, and the page size is 25, then `page` could be 1, 2, 3, or 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items.
  - `pages` integer, required — The total number of pages of results. For example, if there are 80 results, and the page size is 25, then `pages` would be 4. The first three pages would contain 25 items each, and the fourth page would contain the five remaining items. If there are no results, then `pages` will be zero.
  - `links` PaginationLink, required — Helpful links to other pages of results
    - `first` Link, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `last` Link, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `prev` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource
    - `next` OptionalLink, required — A link to a related resource, or an empty object if there is no resource to link to
      - `href` string, url — A URL
      - `type` string — The type of resource, or the type of relationship to the parent resource

## Other responses

- `400` — The request contained errors.
- `500` — An error occurred on ShipEngine's side. > This error will automatically be reported to our engineers.

---

[API](https://skmtc.net/shipengine/apis/shipengine-api.md) · [All operations](https://skmtc.net/shipengine/apis/shipengine-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/shipengine/shipengine-api/revisions/6af91511d87e/schema)