---
title: "List Pins"
method: GET
path: "/pins"
tags: ["pins"]
---

# List Pins

`GET /pins`

Get a list of the Pins owned by the "operation user_account".
- By default, the "operation user_account" is the token user_account.
- All Pins owned by the "operation user_account" are included, regardless of who owns the board they are on.
Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".

## Query parameters

- `bookmark` string
- `page_size` integer
- `pin_filter` 'exclude_native' | 'exclude_repins' | 'has_been_promoted'
- `include_protected_pins` boolean
- `pin_type` 'PRIVATE'
- `creative_types` string[]
- `ad_account_id` string

## Response `200`

Success

- object
  - `items` object[], required
    - `id` string
    - `created_at` string, date-time
    - `link` string, nullable
    - `title` string, nullable
    - `description` string, nullable
    - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. \"#6E7874\".
    - `alt_text` string, nullable
    - `creative_type` 'REGULAR' | 'VIDEO' | 'SHOPPING' | 'CAROUSEL' | 'MAX_VIDEO' | 'SHOP_THE_PIN' | 'COLLECTION' | 'IDEA' | 'SHOWCASE' | 'QUIZ' — Ad creative type enum. </p><strong>Note:</strong> SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.
    - `board_id` string — The board to which this Pin belongs.
    - `board_section_id` string, nullable — The board section to which this Pin belongs.
    - `board_owner` BoardOwner
      - `username` string
    - `is_owner` boolean — Whether the "operation user_account" is the Pin owner.
    - `media` PinMedia — Pin media objects.
      - `media_type` string
    - `media_source` union — Pin media source.
      - PinMediaSourceImageBase64 — Base64-encoded image media source
        - `source_type` 'image_base64', required
        - `content_type` 'image/jpeg' | 'image/png', required
        - `data` string, required
        - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
      - PinMediaSourceImageURL — Image URL-based media source
        - `source_type` 'image_url', required
        - `url` string, required
        - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
      - PinMediaSourceVideoID — Video ID-based media source
        - `source_type` 'video_id', required
        - `cover_image_url` string — Cover image url.
        - `cover_image_content_type` 'image/jpeg' | 'image/png' — Content type for cover image Base64.
        - `cover_image_data` string — Cover image Base64.
        - `media_id` string, required
        - `is_standard` boolean — Set the parameter to false to create the new simplified Pin instead of the standard pin. Currently the field is only available to a list of beta users.
      - PinMediaSourceImagesBase64 — Multiple Base64-encoded images media source
        - `source_type` 'multiple_image_base64'
        - `items` object[], required — Array with image objects.
          - `title` string
          - `description` string
          - `link` string — Destination link for the image.
          - `content_type` 'image/jpeg' | 'image/png', required
          - `data` string, required — Image to upload as base64 string.
        - `index` integer
      - PinMediaSourceImagesURL — Multiple images urls-based media source
        - `source_type` 'multiple_image_urls'
        - `items` object[], required — Array with image objects.
          - `title` string
          - `description` string
          - `link` string — Destination link for the image.
          - `url` string, required — URL of image to upload.
        - `index` integer
      - PinMediaSourcePinURL — Pin URL-based media source for product pin creation. Currently the field is only available to a list of beta users.
        - `source_type` 'pin_url', required
        - `is_affiliate_link` boolean — This is an affiliate link or sponsored product. The FTC requires disclosure for paid partnerships and affiliate products.
    - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. <a href="https://help.pinterest.com/article/save-pins-on-pinterest">Learn more</a>.
    - `is_standard` boolean — Whether the Pin is standard or not. See documentation on <a href="https://developers.pinterest.com/docs/content/update/">Changes to Pin creation</a> for more information.
    - `has_been_promoted` boolean — Whether the Pin has been promoted or not.
    - `note` string, nullable — Private note for this Pin. <a href="https://help.pinterest.com/en/article/add-notes-to-your-pins">Learn more</a>.
  - `bookmark` string, nullable

## Other responses

- `400` — Invalid pin filter value
- `default` — Unexpected error

## Changes

- **2023-08-17** (v5) `0ff12596bafd` — 2 info
  - added the new optional `query` request parameter `page_size`
  - added the optional property `allOf[subschema #2]/items/items/media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #6: Pin URL]/is_affiliate_link` to the response with the `200` status
- **2023-07-14** (v5) `52586a274771` — 2 breaking, 11 info
  - the response property `allOf[subschema #2]/items/items/media_source/allOf[subschema #1: Pin media source]/oneOf[subschema #3: Video ID]/cover_image_url` became optional for the status `200`
  - added `#/components/schemas/PinMediaSourcePinURL` to the `allOf[subschema #2]/items/items/media_source/allOf[subschema #1: Pin media source]/` response property `oneOf` list for the response status `200`
  - added the new enum value `has_been_promoted` to the `query` request parameter `pin_filter`
  - added the enum value `COLLECTION` to the property `items/` of the `query` request parameter `creative_types`
  - …9 more
- …earlier changes not shown

[Full history](https://skmtc.dev/pinterest/apis/pinterest-rest-api/changes/pins/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-service-production.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/0ff12596bafd/schema)