---
title: "List labels"
method: GET
path: "/ad_accounts/{ad_account_id}/labels"
tags: ["labels"]
---

# List labels

`GET /ad_accounts/{ad_account_id}/labels`

## Request

- Base URL: `https://api.pinterest.com/v5`
- URL: `https://api.pinterest.com/v5/ad_accounts/{ad_account_id}/labels`
- Auth: OAuth 2
  - Authorization code: `https://www.pinterest.com/oauth/`
  - Token URL: `https://api.pinterest.com/v5/oauth/token` scopes: `ads:read`
- TypeScript: <https://skmtc.dev/pinterest/apis/pinterest-rest-api/docs/ad_accounts/:ad_account_id/labels/get.ts> (a function with typed inputs; its response is checked against the schema)

[Closed beta](/docs/getting-started/using-beta-and-restricted-features/)

See a list of labels for assets that your account owns, and filter the list by different criteria.
If no filter is provided, it will default to labels associated with the ad account id.

## Path parameters

- `ad_account_id` string, required

## Query parameters

- `campaign_ids` CampaignIdType[]
- `label_ids` QueryLabelIdsItems[]
- `entity_statuses` QueryLabelEntityStatusesItems[]
- `label_types` QueryLabelTypesItems[]
- `bookmark` string
- `page_size` integer

## Response `200`

The request has succeeded.

- object
  - `bookmark` string, nullable
  - `items` Label[], required
    - `id` string, required
    - `label_type` 'BRAND' | 'CUSTOM' | 'null', nullable, required: Category for the labeled items. You can apply one BRAND label to a campaign. You can apply 30 CUSTOM labels to a campaign.
    - `status` 'ACTIVE' | 'ARCHIVED' | 'null', nullable: The new status you want to give the label, either `ACTIVE` (in use) or no longer in use (`ARCHIVED`).
    - `value` string, required: Label name. 100-character limit.

## Other responses

- `400`: The request could not be understood by the server due to unexpected data.
- `401`: Authentication is required and has either failed or not been provided.
- `403`: The request was valid, but the server is refusing action. The user might not have the necessary permissions for a resource.
- `404`: The requested resource could not be found on this server.
- `429`: The user has sent too many requests in a given amount of time and is being rate limited.
- `default`: An unexpected error response.

## Changes

- **2026-06-04** (v5) `b698c180678a`: 1 breaking, 7 info
  - the response's body type changed from no type to `object` for status `200`
  - removed `#/components/schemas/Paginated, subschema #2` from the response body `allOf` list for the response status `200`
  - added the non-success response with the status `401`
  - added the non-success response with the status `403`
  - …4 more
- **2025-10-16** (v5) `14c297539b64`: 6 breaking, 16 warning, 2 info
  - the response property `allOf[subschema #2]/items/items/errors/items/data/label_type` became nullable for the status `200`
  - the response property `allOf[subschema #2]/items/items/errors/items/data/parent_type` became nullable for the status `200`
  - the response property `allOf[subschema #2]/items/items/errors/items/data/status` became nullable for the status `200`
  - the response property `allOf[subschema #2]/items/items/labels/items/label_type` became nullable for the status `200`
  - …20 more
- **2025-08-14** (v5) `7d64d863909a`: 4 breaking, 1 info
  - for the `query` request parameter `entity_statuses`, default value was changed from `ACTIVE, PAUSED` to `ACTIVE`
  - removed the enum value `DELETED_DRAFT` from the property `items/` of the `query` request parameter `entity_statuses`
  - removed the enum value `DRAFT` from the property `items/` of the `query` request parameter `entity_statuses`
  - removed the enum value `PAUSED` from the property `items/` of the `query` request parameter `entity_statuses`
  - …1 more
- …earlier changes not shown

[Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/labels/get.md)

---

[API](https://skmtc.dev/pinterest/apis/pinterest-rest-api.md) - [All operations](https://skmtc.dev/pinterest/apis/pinterest-rest-api/llms.txt) - [OpenAPI document](https://skmtc.dev/pinterest/apis/pinterest-rest-api/revisions/b698c180678a?raw)