PIpinterest
pins

Get multiple Pin analytics

Changed on

This endpoint is currently in beta and not available to all apps. Learn more.

Get analytics for multiple pins owned by the "operation user_account" - or on a group board that has been shared with this account.

  • The maximum number of pins supported in a single request is 100.
  • By default, the "operation user_account" is the token user_account.

Optional: Business Access: Specify an ad_account_id (obtained via List ad accounts) to use the owner of that ad_account as the "operation user_account". In order to do this, the token user_account must have one of the following Business Access roles on the ad_account:

  • For Pins on public or protected boards: Admin, Analyst.
  • For Pins on secret boards: Admin.

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.

get/pins/analytics

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_idsPinterestLibIntegerFormatType[] required

List of Pin IDs.

start_datestring date required

Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today.

end_datestring date required

Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date.

app_types'ALL' | 'MOBILE' | 'TABLET' | 'WEB'

Apps or devices to get data for, default is all.

metric_typesMultiPinsAnalyticsMetricTypesItem[] required

Pin metric types to get data for.

ad_account_idstring

Unique identifier of an ad account.

Response

The request has succeeded.

object required

Changes

  • v5b698c180678aRevision changes
    • warning

      for the query request parameter metric_types, the type of property items/ changed from no type to string

    • info

      added the enum value IMPRESSION to the property items/ of the query request parameter metric_types

    • info

      added the enum value OUTBOUND_CLICK to the property items/ of the query request parameter metric_types

    • info

      added the enum value PIN_CLICK to the property items/ of the query request parameter metric_types

    • info

      added the enum value PROFILE_VISIT to the property items/ of the query request parameter metric_types

    • info

      added the enum value QUARTILE_95_PERCENT_VIEW to the property items/ of the query request parameter metric_types

    • info

      added the enum value SAVE to the property items/ of the query request parameter metric_types

    • info

      added the enum value SAVE_RATE to the property items/ of the query request parameter metric_types

    • info

      added the enum value TOTAL_COMMENTS to the property items/ of the query request parameter metric_types

    • info

      added the enum value TOTAL_REACTIONS to the property items/ of the query request parameter metric_types

    • info

      added the enum value USER_FOLLOW to the property items/ of the query request parameter metric_types

    • info

      added the enum value VIDEO_10S_VIEW to the property items/ of the query request parameter metric_types

    • info

      added the enum value VIDEO_AVG_WATCH_TIME to the property items/ of the query request parameter metric_types

    • info

      added the enum value VIDEO_MRC_VIEW to the property items/ of the query request parameter metric_types

    • info

      added the enum value VIDEO_START to the property items/ of the query request parameter metric_types

    • info

      added the enum value VIDEO_V50_WATCH_TIME to the property items/ of the query request parameter metric_types

    • info

      added the non-success response with the status

  • v589c27ed39cfdRevision changes
    • breaking

      the query request parameter pin_ids became required

    • info

      the endpoint scheme security client_credentials was added to the API

    • info

      added the enum value PROFILE_VISIT to the property items/oneOf[subschema #1]/ of the query request parameter metric_types

    • info

      added the enum value USER_FOLLOW to the property items/oneOf[subschema #1]/ of the query request parameter metric_types