List Labels
GET /v1/labels
This endpoint returns a list of labels that you've created. 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.
Query Parameters
Query Parameter | Type | Description |
---|---|---|
label_status | enumerated string, processing , completed , error , voided | Only return labels that are currently in the specified status |
carrier_id | string ex: se-28529731 | Only return labels for a specific carrier account |
service_code | string ex: usps_first_class_mail | Only return labels for a specific carrier service |
tracking_number | string ex: 1Z5615280351136446 | Only return labels with a specific tracking number |
batch_id | string ex: se-28529731 | Only return labels that were created in a specific batch |
warehouse_id | string ex: se-28529731 | Only return labels that originate from a specific warehouse |
created_at_start | date string (ISO 8601 Standard) ex: 2019-07-25T15:24:46.657Z | Only return labels that were created on or after a specific date/time |
created_at_end | date string (ISO 8601 Standard) ex: 2019-07-25T15:24:46.657Z | Only return labels that were created on or before a specific date/time |
page | integer ex. 100 | 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. |
page_size | integer ex. 100 | The number of labels to return per response. Defaults to 25. |
sort_dir | enumerated string asc or desc | Controls the sort order of the query. Defaults to desc . |
sort_by | enumerated string modified_at , created_at | Controls which property the query is sorted by. Defaults to created_at |
Example Request
The following example demonstrates how to query for the most recent 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
.