PIpinterest
pins

List Pins

Changed on 
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).
get/pins

Request

  • Base URL
    https://api.pinterest.com/v5
  • Auth
    • OAuth 2
      Authorization codehttps://www.pinterest.com/oauth/
      Token URLhttps://api.pinterest.com/v5/oauth/token
      Scopesboards:read, pins:read
    • or OAuth 2
      Client credentials
      Token URLhttps://api.pinterest.com/v3/oauth/access_token/
      Scopesboards:read, pins:read
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Query parameters

pin_filter'exclude_native' | 'exclude_repins' | 'has_been_promoted'

The filter to apply to the pins

pin_metricsboolean

Specify whether to return 90d and lifetime Pin metrics. Total comments and total reactions are only available with lifetime Pin metrics. If Pin was created before 2023-03-20 lifetime metrics will only be available for Video and Idea Pin formats. Lifetime metrics are available for all Pin formats since then.

include_protected_pinsboolean

Whether to include protected pins in the results

pin_type'PRIVATE'

The type of pins to return, currently only enabled for private pins

creative_typesCreativeType[]

Pin creative types filter. Note: SHOP_THE_PIN has been deprecated. Please use COLLECTION instead.

ad_account_idstring

Unique identifier of an ad account.

domainstring

Only return pins with links that match the exact domain. Domain should not include 'www.' prefix. For example, 'pinterest.com' is a valid domain, but 'www.pinterest.com' is not (will not match any pins).

domainsstring[]

Only return pins with links whose domain matches any value in the list. Values are joined comma-separated on the wire (e.g. ?domains=instagram.com,jcpenney.com).

include_product_tag_objboolean

Include product tag objects in the response with their associated links.

bookmarkstring

Cursor used to fetch the next page of items

page_sizeinteger

Maximum number of items to include in a single page. See documentation on Pagination for more information.

Response

The request has succeeded.

bookmarkstring nullable

Example response

{
  "items": [
    {
      "media": {
        "images": {
          "150x150": {
            "width": 150,
            "height": 150,
            "url": "https://i.pinimg.com/150x150/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
          },
          "400x300": {
            "width": 400,
            "height": 300,
            "url": "https://i.pinimg.com/400x300/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
          },
          "600x": {
            "width": 600,
            "height": 600,
            "url": "https://i.pinimg.com/600x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
          },
          "1200x": {
            "width": 1200,
            "height": 1200,
            "url": "https://i.pinimg.com/1200x/0d/f6/f1/0df6f1f0bfe7aaca849c1bbc3607a34b.jpg"
          }
        }
      },
      "pin_metrics": {
        "90d": {
          "pin_click": 7,
          "impression": 2,
          "clickthrough": 3
        },
        "lifetime_metrics": {
          "pin_click": 7,
          "impression": 2,
          "clickthrough": 3,
          "reaction": 10,
          "comment": 2
        }
      }
    }
  ]
}

Changes

  • v5b698c180678aRevision changes
    • breaking

      removed the required property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • warning

      removed the optional property // from the response with the status

    • info

      added the new optional query request parameter domain

    • info

      added the new optional query request parameter domains

    • info

      added the new optional query request parameter include_product_tag_obj

    • info

      added the enum value APP to the property items/ of the query request parameter creative_types

    • info

      added to the / response property allOf list for the response status

  • v514c297539b64Revision changes
    • warning

      removed the optional property // from the response with the status

    • warning

      added the new COLLAGE enum value to the /// response property for the response status

    • warning

      added the new MAX_WIDTH_REGULAR_COLLECTION enum value to the /// response property for the response status

    • warning

      added the new MAX_WIDTH_VIDEO_COLLECTION enum value to the /// response property for the response status

    • info

      added the enum value COLLAGE to the property items/ of the query request parameter creative_types

    • info

      added the enum value MAX_WIDTH_REGULAR_COLLECTION to the property items/ of the query request parameter creative_types

    • info

      added the enum value MAX_WIDTH_VIDEO_COLLECTION to the property items/ of the query request parameter creative_types