# List Labels To get a list of labels you've [created](/create-labels) in ShipStation, you make a GET call to the `/v2/labels` endpoint. By default, this endpoint returns all labels, 25 at a time, starting with those most recently created. You can get labels in one of the following ways: - Use **query parameters** to filter the results as well as control their sort order and the number of results returned at a time. - Get by **label ID** if you have the `label_id` and need only your specified label details. - Get by **external shipment ID** if you have the `external_shipment_id` ## Use Query Parameters Request & Response **GET /v2/labels** 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`. ### 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 ex: `se-28529731` | | `service_code` | *string* | Only return labels for a specific carrier service 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](/batch-labels) ex: `se-28529731` | | `warehouse_id` | *string* | Only return labels that originate from a specific 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, maximum is 500. 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`, `voided_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. ## Get Label by ID Request & Response **GET /v2/labels/:label_id** ```http GET /v2/labels/se-28529731 HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json ``` **Response** ```json { "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "ship_date": "2024-09-23T00:00:00.000Z", "created_at": "2024-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ {} ], "tracking_number": "782758401696", "is_return_label": true, "rma_number": "string", "is_international": true, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "carrier_default", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": false, "voided_at": "", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "packages": [ {} ], "alternative_identifiers": [ {} ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" } ``` ## Get Label by External Shipment ID Request & Response **GET /v2/labels/external_shipment_id/:external_shipment_id** ```http GET /v2/labels/external_shipment_id/0bcb569d-1727-4ff9-ab49-b2fec0cee5ae HTTP/1.1 Host: api.shipstation.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json ``` **Response** ```json { "label_id": "se-28529731", "status": "processing", "shipment_id": "se-28529731", "ship_date": "2024-09-23T00:00:00.000Z", "created_at": "2024-09-23T15:00:00.000Z", "shipment_cost": { "currency": "string", "amount": 0 }, "insurance_cost": { "currency": "string", "amount": 0 }, "requested_comparison_amount": { "currency": "string", "amount": 0 }, "rate_details": [ { "rate_detail_type": "uncategorized", "carrier_description": "string", "carrier_billing_code": "string", "carrier_memo": "string", "amount": { "currency": "string", "amount": 0 }, "rate_detail_attributes": { "tax_type": "vat", "tax_code": "string", "tax_percentage": 0 }, "billing_source": "string" } ], "tracking_number": "782758401696", "is_return_label": false, "rma_number": "string", "is_international": false, "batch_id": "se-28529731", "carrier_id": "se-28529731", "charge_event": "", "service_code": "usps_first_class_mail", "package_code": "small_flat_rate_box", "voided": false, "voided_at": "", "label_format": "pdf", "display_scheme": "label", "label_layout": "4x6", "trackable": true, "label_image_id": "img_DtBXupDBxREpHnwEXhTfgK", "carrier_code": "dhl_express", "tracking_status": "unknown", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": null, "handoff_code": null }, "insurance_claim": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "packages": [ { "package_id": 0, "package_code": "small_flat_rate_box", "weight": { "value": 0, "unit": "pound" }, "dimensions": { "unit": "inch", "length": 0, "width": 0, "height": 0 }, "insured_value": { "0": { "currency": "usd", "amount": 0 }, "currency": "string", "amount": 0 }, "tracking_number": "1Z932R800392060079", "label_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "pdf": "http://api.shipstation.com/v2/labels/se-28529731", "png": "http://api.shipstation.com/v2/labels/se-28529731", "zpl": "http://api.shipstation.com/v2/labels/se-28529731" }, "form_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "qr_code_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "type": "string" }, "paperless_download": { "href": "http://api.shipstation.com/v2/labels/se-28529731", "instructions": null, "handoff_code": null }, "label_messages": { "reference1": null, "reference2": null, "reference3": null }, "external_package_id": "string", "content_description": "Hand knitted wool socks", "sequence": 0, "has_label_documents": true, "has_form_documents": true, "has_qr_code_documents": true, "has_paperless_label_documents": true, "alternative_identifiers": [ { "type": "last_mile_tracking_number", "value": "12345678912345678912" } ] } ], "alternative_identifiers": [ { "type": "last_mile_tracking_number", "value": "12345678912345678912" } ], "tracking_url": "https://www.fedex.com/fedextrack/?action=track&trackingnumber=1234" } ```