--- 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". Disclaimer: There are known performance issues when filtering by field `creative_type` and including protected pins. If your request is timing out in this scenario, we encourage you to use [GET List Pins on Board](/docs/api/v5/#operation/boards/list_pins). ## Query parameters - `pin_filter` 'exclude_native' | 'exclude_repins' | 'has_been_promoted' - `pin_metrics` boolean - `include_protected_pins` boolean - `pin_type` 'PRIVATE' - `creative_types` CreativeType[] - `ad_account_id` string - `domain` string - `domains` string[] - `include_product_tag_obj` boolean - `bookmark` string - `page_size` integer ## Response `200` The request has succeeded. - object - `bookmark` string, nullable - `items` Pin[], required - `ai_disclosures` AiDisclosures — AI disclosure declarations the creator has made about the Pin. - `values` AiDisclosureItem[], required — List of AI disclosure declarations the creator has made about this Pin. - `board_id` string — The board to which this Pin belongs. - `board_owner` BoardOwner - `username` string - `board_section_id` string, nullable — The board section to which this Pin belongs. - `created_at` string, date-time - `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' — Ad creative type enum. **Note:** SHOP_THE_PIN has been deprecated. Please use COLLECTION instead. - `dominant_color` string, nullable — Dominant pin color. Hex number, e.g. `#6E7874`. - `has_been_promoted` boolean — Whether the Pin has been promoted or not. - `id` string, required - `is_owner` boolean — Whether the "operation user_account" is the Pin owner. - `is_product` boolean — Whether the Pin is a product Pin. - `is_standard` boolean — Whether the Pin is standard or not. See documentation on [Changes to Pin creation](/docs/api-features/content-overview/) for more information. - `media` union — Pin media that can be an image, video, or a mix of both. - object — Pin with image. - `images` ImageSize - `1200x` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `150x150` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `400x300` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `600x` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `media_type` 'image', required - object — Pin with video. - `cover_image_url` string - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time. - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time. - `images` ImageSize - `1200x` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `150x150` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `400x300` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `600x` ImageDetails - `height` integer, nullable, required - `url` string, required - `width` integer, nullable, required - `media_type` 'video', required - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps. - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps. - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time. - object — Pin with multiple images. - `items` ImageMetadata[] - `description` string, nullable - `images` ImageSize - `1200x` ImageDetails - … - `150x150` ImageDetails - … - `400x300` ImageDetails - … - `600x` ImageDetails - … - `item_type` 'image', required — Discriminator literal identifying this as image metadata inside a `PinMediaMetadata` payload. - `link` string, nullable - `title` string, nullable - `media_type` 'multiple_images', required - object — Pin with multiple videos. - `items` VideoMetadataWithItemType[] - `cover_image_url` string - `duration` number, nullable — Duration (in miliseconds). Field maybe null after creation due to video processing time. - `height` integer, nullable — Height (in pixels). Field maybe null after creation due to video processing time. - `item_type` 'video', required — Discriminator literal identifying this as video metadata inside a `PinMediaMetadata` payload. - `video_url` string, nullable — Video url (720p). **Note:** This field is limited and not available to all apps. - `video_url_hls` string, nullable — Video url (HLS). **Note:** This field is limited and not available to all apps. - `width` integer, nullable — Width (in pixels). Field maybe null after creation due to video processing time. - `media_type` 'multiple_videos', required - object — Pin with a mix of images and videos. - `items` PinMediaMetadata[] - union — Per-item entry inside `PinMedia.items` for mixed image/video pins. Discriminated by `item_type`. - object - … - object - … - `media_type` 'multiple_mixed', required - `parent_pin_id` string, nullable — The source pin id if this pin was saved from another pin. [Learn more](https://help.pinterest.com/article/save-pins-on-pinterest). - `pin_metrics` object, nullable — Pin metrics with associated time intervals if any. ## 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. --- [API](https://skmtc.net/pinterest/apis/pinterest-rest-api.md) · [All operations](https://skmtc.net/pinterest/apis/pinterest-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/pinterest/pinterest-rest-api/revisions/b698c180678a/schema)