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

# List ads

`GET /ad_accounts/{ad_account_id}/ads`

## Request

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

List ads that meet the filters provided:
    - Listed campaign ids or ad group ids or ad ids
    - Listed entity statuses

If no filter is provided, all ads in the ad account are returned.

**Note:**
Provide only `campaign_id` or `ad_group_id` or `ad_id`. Do not provide more than one type.

Review status is provided for each ad; if `review_status` is `REJECTED`, the `rejected_reasons` field will contain additional information.

For more, see [Pinterest advertising standards](https://policy.pinterest.com/en/advertising-guidelines).

## Path parameters

- `ad_account_id` string, required

## Query parameters

- `bookmark` string
- `page_size` integer
- `order` 'ASCENDING' | 'DESCENDING'
- `campaign_ids` CampaignIdType[]
- `ad_group_ids` PinterestLibIntegerFormatType[]
- `ad_ids` PinterestLibIntegerFormatType[]
- `entity_statuses` EntityStatus[]

## Response `200`

The request has succeeded.

- object
  - `bookmark` string, nullable
  - `items` Ad[], required
    - `ad_account_id` string, required: The ID of the advertiser that this ad belongs to.
    - `ad_group_id` string, required: ID of the ad group that contains the ad.
    - `android_deep_link` string, nullable: Deep link URL for Android devices.
    - `campaign_id` string, required: ID of the ad campaign that contains this ad.
    - `carousel_android_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on Android.
    - `carousel_destination_urls` string[], nullable: Comma-separated destination URLs for the carousel pin to promote.
    - `carousel_ios_deep_links` string[], nullable: Comma-separated deep links for the carousel pin on iOS.
    - `carting_platform_type` integer: The vendor platform type of the carting ad. 1 for MIKMAK, 2 for PEAR.
    - `carting_products` CartingProduct[]: Array of carting/WTB products for the ad.
      - `carting_product_id` string, required: the internal Pinterest carting product id (different from industry product id)
      - `display_preferred_retailers_only` boolean: Whether to display only the preferred retailers for the carting product
      - `display_product_price` boolean: Whether to display the price for the carting product
      - `preferred_retailers` CartingRetailer[]: A sorted array of preferred retailers for the carting product
        - `retailer_id` string, required: Unique identifier for the retailer
        - `retailer_name` string, required: Name of the retailer
      - `randomize_preferred_retailers` boolean: Whether to randomize preferred retailers for the carting product
    - `click_tracking_url` string, nullable: Tracking url for the ad clicks.
    - `collection_items_destination_url_template` string, nullable: Destination URL template for all items within a collections drawer.
    - `collections_header_type` 'SHOP_THIS_COLLECTION' | 'EXPLORE_THIS_COLLECTION' | 'NO_HEADER' | 'null', nullable: Collections ad header type for ads
    - `created_time` integer: Pin creation time. Unix timestamp in seconds.
    - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' | 'COLLAGE' | 'MAX_WIDTH_REGULAR_COLLECTION' | 'MAX_WIDTH_VIDEO_COLLECTION' | 'APP', required: Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
    - `customizable_cta_type` 'GET_OFFER' | 'LEARN_MORE' | 'ORDER_NOW' | 'SHOP_NOW' | 'SIGN_UP' | 'SUBSCRIBE' | 'BUY_NOW' | 'CONTACT_US' | 'GET_QUOTE' | 'VISIT_SITE' | 'APPLY_NOW' | 'BOOK_NOW' | 'REQUEST_DEMO' | 'REGISTER_NOW' | 'FIND_A_DEALER' | 'ADD_TO_CART' | 'WATCH_NOW' | 'READ_MORE' | 'BUY_TICKETS' | 'DONATE_NOW' | 'DOWNLOAD' | 'EXPLORE_MORE' | 'FIND_A_LOCATION' | 'FIND_RETAILERS' | 'GET_DEAL' | 'GET_RECIPE' | 'GET_SHOWTIMES' | 'ON_SALE' | 'PLAY_GAME' | 'TRY_IT' | 'TAKE_A_PEEK' | 'null', nullable: Select a call to action (CTA) to display below your ad. Available only for ads with direct links enabled. CTA options for consideration and conversion campaigns are LEARN_MORE, SHOP_NOW, BOOK_NOW, SIGN_UP, VISIT_SITE, BUY_NOW, GET_OFFER, ORDER_NOW, ADD_TO_CART (for conversion campaigns with add to cart conversion events only)
    - `destination_url` string, nullable: Destination URL.
    - `disclosure_type` 'NO_DISCLOSURE' | 'PRESCRIBING_INFORMATION' | 'PRESCRIBING_INFORMATION_BOX_WARNING' | 'IMPORTANT_SAFETY_INFO' | 'MED_GUIDE' | 'PATIENT_INFORMATION' | 'null', nullable: Type of information in the page referenced by `disclosure_url`, provided either by the Food and Drug Administration (FDA) or the manufacturer.
    - `disclosure_url` string, nullable: URL for a page that provides disclosures about a pharmaceutical product, such as potential side effects. Make sure the URL takes the user directly to the disclosure content and the referenced site is secure.
    - `grid_click_type` 'CLOSEUP' | 'DIRECT_TO_DESTINATION', nullable: Where a user is taken after clicking on an ad in grid. **Note:** This parameter is read-only and is set to `DIRECT_TO_DESTINATION` by default for direct links supported ads. `grid_click_type` values provided will be ignored.
    - `id` string, required: The ID of this ad.
    - `ios_deep_link` string, nullable: Deep link URL for iOS devices.
    - `is_carting` boolean: Is the ad a carting/WTB ad?
    - `is_collage_accepted_terms` boolean: Whether the advertiser has accepted the terms and conditions for collage ad.
    - `is_collage_single_destination` boolean: Whether the collage ad has a single destination url override.
    - `is_pin_deleted` boolean: Is original pin deleted?
    - `is_removable` boolean: Is pin repinnable?
    - `lead_form_id` string, nullable: Lead form ID for lead ad generation.
    - `name` string, nullable: Name of the ad - 255 chars max.
    - `pin_id` string, required: Pin ID. This field may only be updated for draft ads.
    - `quiz_pin_data` QuizPinData, nullable: This field includes all quiz data including questions, options, and results.
      - `questions` QuizPinQuestion[]
        - `options` QuizPinOption[]
          - `id` number
          - `text` string
        - `question_id` number
        - `question_text` string
      - `results` QuizPinResult[]
        - `android_deep_link` string
        - `destination_url` string
        - `ios_deep_link` string
        - `organic_pin_id` string
        - `result_id` number
      - `tie_breaker_custom_result` QuizPinResult, nullable: The result, and link out, based on the user’s choice.
        - `android_deep_link` string
        - `destination_url` string
        - `ios_deep_link` string
        - `organic_pin_id` string
        - `result_id` number
      - `tie_breaker_type` 'RANDOM' | 'CUSTOM': Quiz ad tie breaker type, default is RANDOM
    - `rejected_reasons` AdDisapprovalReasons[], required: Enum reason why the pin was rejected. Returned if `review_status` is "REJECTED".
    - `rejection_labels` string[], required: Text reason why the pin was rejected. Returned if `review_status` is "REJECTED".
    - `review_status` 'OTHER' | 'PENDING' | 'REJECTED' | 'APPROVED', required: Ad review status
    - `status` 'ACTIVE' | 'PAUSED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT': Entity status
    - `summary_status` 'APPROVED' | 'PAUSED' | 'PENDING' | 'REJECTED' | 'ADVERTISER_DISABLED' | 'ARCHIVED' | 'DRAFT' | 'DELETED_DRAFT', required: Summary status for pin promotions
    - `tracking_urls` TrackingUrls, nullable: Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see [Third-party and dynamic tracking](https://help.pinterest.com/en/business/article/third-party-and-dynamic-tracking).
      - `audience_verification` string[]
      - `buyable_button` string[]
      - `click` string[]
      - `engagement` string[]
      - `impression` string[]
    - `type` string, required: Always "ad".
    - `updated_time` integer: Last update time. Unix timestamp in seconds.
    - `view_tracking_url` string, nullable: Tracking URL for ad impressions.

## 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`: 2 breaking, 7 info
  - for the `query` request parameter `order`, default value `ASCENDING` was added
  - 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`
  - …5 more
- **2025-12-11** (v5) `537bde5a50b1`: 2 info
  - added the optional property `allOf[subschema #2]/items/items/allOf[#/components/schemas/AdCommon]/disclosure_type` to the response with the `200` status
  - added the optional property `allOf[subschema #2]/items/items/allOf[#/components/schemas/AdCommon]/disclosure_url` to the response with the `200` status
- …earlier changes not shown

[Operation history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/ad_accounts/:ad_account_id/ads/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)