PIpinterest
user_account

Get user account top pins analytics

Changed on

Gets analytics data about a user's top pins (limited to the top 50).

  • By default, the "operation user_account" is the token user_account.

Optional: Business Access: Specify an ad_account_id to use the owner of that ad_account as the "operation user_account".

get/user_account/analytics/top_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
      Scopespins:read, user_accounts:read
    • or OAuth 2
      Client credentials
      Token URLhttps://api.pinterest.com/v3/oauth/access_token/
      Scopespins:read, user_accounts:read
  • TypeScript
    A function with typed inputs. Its response is checked against the schema.

Query parameters

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.

sort_by'ENGAGEMENT' | 'SAVE' | 'IMPRESSION' | 'OUTBOUND_CLICK' | 'PIN_CLICK' required

Sort metric for top pins analytics.

Specify sorting order for metrics

from_claimed_content'OTHER' | 'CLAIMED' | 'BOTH'

Filter on Pins that match your claimed domain.

pin_format'ALL' | 'ORGANIC_IMAGE' | 'ORGANIC_PRODUCT' | 'ORGANIC_VIDEO' | 'ADS_STANDARD' | 'ADS_PRODUCT' | 'ADS_VIDEO' | 'ADS_IDEA'

Pin formats to get data for, default is all.

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

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

content_type'ALL' | 'PAID' | 'ORGANIC'

Filter to paid or organic data. Default is all.

source'ALL' | 'YOUR_PINS' | 'OTHER_PINS'

Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts

metric_typesQuerymetrictypesItems[]

Metric types to get data for, default is all.

num_of_pinsinteger

Number of pins to include, default is 10. Max is 50.

created_in_last_n_days30

Get metrics for pins created in the last "n" days.

ad_account_idstring

Unique identifier of an ad account.

Response

The request has succeeded.

sort_by'ENGAGEMENT' | 'SAVE' | 'IMPRESSION' | 'OUTBOUND_CLICK' | 'PIN_CLICK'

Sort metric for top pins analytics.

Changes

  • v5b698c180678aRevision changes
    • info

      for the query request parameter created_in_last_n_days, the type was generalized from integer to number

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

    • info

      added the non-success response with the status

  • v589c27ed39cfdRevision changes
    • breaking

      removed the enum value PRODUCT from the query request parameter pin_format

    • breaking

      removed the enum value REGULAR from the query request parameter pin_format

    • breaking

      removed the enum value VIDEO from the query request parameter pin_format

    • info

      the endpoint scheme security client_credentials was added to the API