openapi: 3.0.3 info: version: 5.13.0 title: Pinterest Analytics API description: This is the description of your API. contact: name: Pinterest, Inc. url: https://developers.pinterest.com/ license: name: MIT url: https://spdx.org/licenses/MIT termsOfService: https://developers.pinterest.com/terms/ servers: - url: https://api.pinterest.com/v5 tags: - name: Analytics paths: /ad_accounts/{ad_account_id}/ad_groups/analytics: get: summary: Get ad group analytics description: 'Get analytics for the specified ad groups in the specified ad_account_id, filtered by the specified options. - The token''s user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager. - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days. - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.' operationId: ad_groups/analytics security: - pinterest_oauth2: - ads:read x-ratelimit-category: ads_analytics x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_ad_group_ids_required' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AdGroupsAnalyticsResponse' description: Success '400': description: Invalid ad account group analytics parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: Invalid ad account group analytics parameters. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Analytics /ad_accounts/{ad_account_id}/ad_groups/targeting_analytics: get: summary: Get targeting analytics for ad groups description: 'Get targeting analytics for one or more ad groups. For the requested ad group(s) and metrics, the response will include the requested metric information (e.g. SPEND_IN_DOLLAR) for the requested target type (e.g. "age_bucket") for applicable values (e.g. "45-49").

- The token''s user_account must either be the Owner of the specified ad account, or have one of the necessary roles granted to them via Business Access: Admin, Analyst, Campaign Manager. - If granularity is not HOUR, the furthest back you can are allowed to pull data is 90 days before the current date in UTC time and the max time range supported is 90 days. - If granularity is HOUR, the furthest back you can are allowed to pull data is 8 days before the current date in UTC time and the max time range supported is 3 days.' operationId: ad_account_targeting_analytics/get security: - pinterest_oauth2: - ads:read x-ratelimit-category: ads_analytics x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_targeting_types' - $ref: '#/components/parameters/query_columns' - $ref: '#/components/parameters/query_granularity' - $ref: '#/components/parameters/query_conversion_attribution_click_window_days' - $ref: '#/components/parameters/query_conversion_attribution_engagement_window_days' - $ref: '#/components/parameters/query_conversion_attribution_view_window_days' - $ref: '#/components/parameters/query_conversion_attribution_conversion_report_time' - $ref: '#/components/parameters/query_attribution_types' responses: '200': content: application/json: schema: $ref: '#/components/schemas/MetricsResponse' description: Success default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Analytics /pins/{pin_id}/analytics: get: summary: Get Pin analytics description: 'Get analytics for a Pin owned by the "operation user_account" - or on a group board that has been shared with this account. - 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.' tags: - Analytics operationId: pins/analytics security: - pinterest_oauth2: - boards:read - pins:read x-ratelimit-category: org_analytics x-sandbox: disabled parameters: - $ref: '#/components/parameters/path_pin_id' - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_pin_analytics_metric_types' - $ref: '#/components/parameters/query_split_field_pins' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: response content: application/json: schema: $ref: '#/components/schemas/PinAnalyticsResponse' '400': description: Invalid pins analytics parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: Invalid pins analytics parameters. '403': description: Not authorized to access board or Pin. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 403 message: Not authorized to access board or Pin. '404': description: Pin not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 404 message: Pin not found. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /pins/analytics: get: summary: Get multiple Pin analytics description: '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.' tags: - Analytics operationId: multi_pins/analytics security: - pinterest_oauth2: - boards:read - pins:read x-ratelimit-category: org_analytics x-sandbox: disabled parameters: - name: pin_ids description: List of Pin IDs. in: query schema: type: array items: type: string pattern: ^\d+$ minItems: 1 maxItems: 100 - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_app_types' - description: Pin metric types to get data for. explode: false in: query name: metric_types required: true schema: type: array items: oneOf: - description: Standard Pin metric types type: string enum: - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK - SAVE - SAVE_RATE - TOTAL_COMMENTS - TOTAL_REACTIONS - description: Video Pin metric types type: string enum: - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK - SAVE - SAVE_RATE - VIDEO_MRC_VIEW - VIDEO_10S_VIEW - QUARTILE_95_PERCENT_VIEW - VIDEO_V50_WATCH_TIME - VIDEO_START - VIDEO_AVG_WATCH_TIME - TOTAL_COMMENTS - TOTAL_REACTIONS style: form - $ref: '#/components/parameters/query_ad_account_id' responses: '200': description: response content: application/json: schema: $ref: '#/components/schemas/BulkPinAnalyticsResponse' '400': description: Invalid pins analytics parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 1 message: Invalid multi_pins analytics parameters. '401': description: Not authorized to access board or Pin. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 7 message: Not authorized to access board or Pin. '404': description: Pin not found. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 50 message: Pin not found. '429': description: 'This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.' content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 8 message: 'This request exceeded a rate limit. This can happen if the client exceeds one of the published rate limits or if multiple write operations are applied to an object within a short time window.' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /user_account/analytics: get: summary: Get user account analytics description: 'Get analytics for the "operation user_account" - 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".' tags: - Analytics operationId: user_account/analytics security: - pinterest_oauth2: - user_accounts:read x-ratelimit-category: org_analytics x-sandbox: disabled parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_metric_types' - $ref: '#/components/parameters/query_split_field_user_account' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': content: application/json: schema: $ref: '#/components/schemas/AnalyticsResponse' description: Success '400': description: Invalid user accounts analytics parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: Invalid user accounts analytics parameters. '403': description: Not authorized to access the user account analytics. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 403 message: Not authorized to access the user account analytics. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /user_account/analytics/top_pins: get: summary: Get user account top pins analytics description: '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".' tags: - Analytics operationId: user_account/analytics/top_pins security: - pinterest_oauth2: - pins:read - user_accounts:read x-ratelimit-category: org_analytics x-sandbox: disabled parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_sort_by' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_metric_types' - $ref: '#/components/parameters/query_num_of_pins' - $ref: '#/components/parameters/query_created_in_last_n_days' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TopPinsAnalyticsResponse' description: Success '403': description: Not authorized to access the user account analytics. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 403 message: Not authorized to access the user account analytics. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /user_account/analytics/top_video_pins: get: summary: Get user account top video pins analytics description: 'Gets analytics data about a user''s top video 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".' tags: - Analytics operationId: user_account/analytics/top_video_pins security: - pinterest_oauth2: - pins:read - user_accounts:read x-ratelimit-category: org_analytics x-sandbox: disabled parameters: - $ref: '#/components/parameters/query_start_date' - $ref: '#/components/parameters/query_end_date' - $ref: '#/components/parameters/query_video_pin_sort_by' - $ref: '#/components/parameters/query_from_claimed_content' - $ref: '#/components/parameters/query_pin_format' - $ref: '#/components/parameters/query_app_types' - $ref: '#/components/parameters/query_content_type' - $ref: '#/components/parameters/query_source' - $ref: '#/components/parameters/query_video_pin_metric_types' - $ref: '#/components/parameters/query_num_of_pins' - $ref: '#/components/parameters/query_created_in_last_n_days' - $ref: '#/components/parameters/query_ad_account_id' responses: '200': content: application/json: schema: $ref: '#/components/schemas/TopVideoPinsAnalyticsResponse' description: Success '403': description: Not authorized to access the user account analytics. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 403 message: Not authorized to access the user account analytics. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: TopVideoPinsAnalyticsResponse: type: object properties: date_availability: type: object properties: latest_available_timestamp: type: number example: 1649116799000 is_realtime: type: boolean example: false pins: type: array items: description: Array with metrics, status, and pin id for the requested metric type: object properties: metrics: description: The metric name and daily value for each requested metric type: object additionalProperties: type: number example: IMPRESSION: 7 QUARTILE_95_PERCENT_VIEW: 2 SAVE: 1 VIDEO_10S_VIEW: 5 VIDEO_AVG_WATCH_TIME: 86989 VIDEO_MRC_VIEW: 2 VIDEO_START: 2 VIDEO_V50_WATCH_TIME: 173979 OUTBOUND_CLICK: 2 data_status: type: object additionalProperties: $ref: '#/components/schemas/DataStatus' pin_id: description: The pin id type: string example: '642396334344813594' sort_by: type: string enum: - SAVE - IMPRESSION - OUTBOUND_CLICK - VIDEO_MRC_VIEW - VIDEO_AVG_WATCH_TIME - VIDEO_V50_WATCH_TIME - QUARTILE_95_PERCENT_VIEW - VIDEO_10S_VIEW - VIDEO_START example: IMPRESSION AdsAnalyticsResponse: type: array items: type: object properties: AD_ID: description: The ID of the ad that this metrics belongs to. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date required: - AD_ID additionalProperties: true example: DATE: '2021-04-01' AD_ID: '547602124502' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 PinAnalyticsMetricsResponse: type: object properties: lifetime_metrics: description: The lifetime metric name and value. type: object additionalProperties: type: integer example: TOTAL_COMMENTS: 10 TOTAL_REACTIONS: 12 daily_metrics: description: Array with the requested daily metric records items: type: object properties: data_status: $ref: '#/components/schemas/DataStatus' date: description: 'Metrics date (UTC): YYYY-MM-DD.' example: '2019-12-01' type: string metrics: description: The metric name and daily value for each requested metric type: object additionalProperties: type: number example: IMPRESSION: 240 OUTBOUND_CLICK: 20 PIN_CLICK: 37 QUARTILE_95_PERCENT_VIEW: 8 SAVE: 20 SAVE_RATE: 0.18 VIDEO_10S_VIEW: 2 VIDEO_AVG_WATCH_TIME: 2507.75 VIDEO_MRC_VIEW: 20 VIDEO_START: 29 VIDEO_V50_WATCH_TIME: 10031 type: array summary_metrics: description: The metric name and value over the requested period for each requested metric type: object additionalProperties: type: number example: IMPRESSION: 240 OUTBOUND_CLICK: 20 PIN_CLICK: 37 QUARTILE_95_PERCENT_VIEW: 8 SAVE: 20 SAVE_RATE: 0.18 VIDEO_10S_VIEW: 2 VIDEO_AVG_WATCH_TIME: 2507.75 VIDEO_MRC_VIEW: 20 VIDEO_START: 29 VIDEO_V50_WATCH_TIME: 10031 Error: title: Error type: object properties: code: type: integer message: type: string required: - code - message AdAccountAnalyticsResponse: type: array items: type: object properties: AD_ACCOUNT_ID: description: The ID of the advertiser that this metrics belongs to. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date required: - AD_ACCOUNT_ID additionalProperties: true example: DATE: '2021-04-01' AD_ACCOUNT_ID: '547602124502' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 AdGroupsAnalyticsResponse: type: array items: type: object properties: AD_GROUP_ID: description: The ID of the ad group that this metrics belongs to. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date required: - AD_GROUP_ID additionalProperties: true example: DATE: '2021-04-01' AD_GROUP_ID: '547602124502' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 ProductGroupAnalyticsResponse: type: array items: type: object properties: PRODUCT_GROUP_ID: description: The ID of the product group that this metrics belongs to. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date required: - PRODUCT_GROUP_ID additionalProperties: true example: DATE: '2021-04-01' PRODUCT_GROUP_ID: '74629351736530' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 AnalyticsResponse: type: object additionalProperties: $ref: '#/components/schemas/AnalyticsMetricsResponse' TopPinsAnalyticsResponse: type: object properties: date_availability: type: object properties: latest_available_timestamp: type: number example: 1649116799000 is_realtime: type: boolean example: false pins: type: array items: description: Array with metrics, status, and pin id for the requested metric type: object properties: metrics: $ref: '#/components/schemas/Metrics' data_status: type: object additionalProperties: $ref: '#/components/schemas/DataStatus' pin_id: description: The pin id type: string example: '642396334344813594' sort_by: type: string enum: - ENGAGEMENT - SAVE - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK example: IMPRESSION MetricsResponse: properties: data: items: type: object type: array example: - targeting_type: KEYWORD targeting_value: christmas decor ideas metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: iphone metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: ipad metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: web metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: web_mobile metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: android_mobile metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: APPTYPE targeting_value: android_tablet metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: GENDER targeting_value: female metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: LOCATION targeting_value: 500 metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: PLACEMENT targeting_value: SEARCH metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: COUNTRY targeting_value: US metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: TARGETED_INTEREST targeting_value: Food and Drinks metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: PINNER_INTEREST targeting_value: Chocolate Cookies metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: AUDIENCE_INCLUDE targeting_value: 254261234567 metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: GEO targeting_value: US:94102 metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: AGE_BUCKET targeting_value: 45-49 metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 - targeting_type: REGION targeting_value: US-CA metrics: AD_GROUP_ID: 2680067996745 DATE: '2022-04-26' SPEND_IN_DOLLAR: 240 type: object ConversionReportAttributionType: type: string description: Attribution type. Refers to the Pinterest Tag endpoints example: INDIVIDUAL enum: - INDIVIDUAL - HOUSEHOLD CampaignsAnalyticsResponse: type: array items: type: object properties: CAMPAIGN_ID: description: The ID of the campaing that this metrics belongs to. type: string pattern: ^\d+$ DATE: description: Current metrics date. Only returned when granularity is a time-based value (`DAY`, `HOUR`, `WEEK`, `MONTH`) type: string format: date required: - CAMPAIGN_ID additionalProperties: true example: DATE: '2021-04-01' CAMPAIGN_ID: '547602124502' SPEND_IN_DOLLAR: 30 TOTAL_CLICKTHROUGH: 216 PinAnalyticsResponse: type: object additionalProperties: $ref: '#/components/schemas/PinAnalyticsMetricsResponse' AdsAnalyticsTargetingType: type: string description: Reporting targeting type example: APPTYPE enum: - KEYWORD - APPTYPE - GENDER - LOCATION - PLACEMENT - COUNTRY - TARGETED_INTEREST - PINNER_INTEREST - AUDIENCE_INCLUDE - GEO - AGE_BUCKET - REGION - AGE_BUCKET_AND_GENDER AnalyticsDailyMetrics: type: object properties: data_status: $ref: '#/components/schemas/DataStatus' date: description: 'Metrics date (UTC): YYYY-MM-DD.' example: '2019-12-01' type: string metrics: $ref: '#/components/schemas/Metrics' AnalyticsMetricsResponse: type: object properties: summary_metrics: description: The metric name and value over the requested period for each requested metric type: object additionalProperties: type: number example: CLOSEUP: 1 CLOSEUP_RATE: 0 ENGAGEMENT: 1 ENGAGEMENT_RATE: 0 IMPRESSION: 240 OUTBOUND_CLICK: 20 OUTBOUND_CLICK_RATE: 0.08 PIN_CLICK: 37 PIN_CLICK_RATE: 0.15 PROFILE_VISIT: 0 QUARTILE_95_PERCENT_VIEW: 8 SAVE: 20 SAVE_RATE: 0.18 VIDEO_10S_VIEW: 2 VIDEO_AVG_WATCH_TIME: 2507.75 VIDEO_MRC_VIEW: 20 VIDEO_START: 29 VIDEO_V50_WATCH_TIME: 10031 daily_metrics: description: Array with the requested daily metric records items: $ref: '#/components/schemas/AnalyticsDailyMetrics' type: array BulkPinAnalyticsResponse: type: object additionalProperties: $ref: '#/components/schemas/PinAnalyticsResponse' Granularity: type: string description: Granularity enum: - TOTAL - DAY - HOUR - WEEK - MONTH DataStatus: description: Metrics availablity, e.g., "READY". example: READY type: string enum: - PROCESSING - READY - ESTIMATE - BEFORE_BUSINESS_CREATED - BEFORE_DATA_RETENTION_PERIOD - BEFORE_PIN_DATA_RETENTION_PERIOD - BEFORE_METRIC_START_DATE - BEFORE_CORE_METRIC_START_DATE - BEFORE_PIN_FORMAT_METRIC_START_DATE - BEFORE_AUDIENCE_METRIC_START_DATE - BEFORE_AUDIENCE_MONTHLY_METRIC_START_DATE - BEFORE_VIDEO_METRIC_START_DATE - BEFORE_CONVERSION_METRIC_START_DATE - PURCHASERS_METRIC_SMALLER_THAN_THRESHOLD - IN_BAD_TAG_DATE - BEFORE_PUBLISHED_METRIC_START_DATE - BEFORE_ASSIST_METRIC_START_DATE - BEFORE_PIN_CREATED - BEFORE_ACCOUNT_CLAIMED - BEFORE_DEMOGRAPHIC_FILTERS_START_DATE - AUDIENCE_SEGMENT_SMALLER_THAN_THRESHOLD - AUDIENCE_TOTAL_SMALLER_THAN_THRESHOLD - BEFORE_PRODUCT_GROUP_FILTER_START_DATE Metrics: description: The metric name and daily value for each requested metric type: object additionalProperties: type: number example: CLOSEUP: 1 CLOSEUP_RATE: 0 ENGAGEMENT: 1 ENGAGEMENT_RATE: 0 IMPRESSION: 240 OUTBOUND_CLICK: 20 OUTBOUND_CLICK_RATE: 0.08 PIN_CLICK: 37 PIN_CLICK_RATE: 0.15 QUARTILE_95_PERCENT_VIEW: 8 SAVE: 20 SAVE_RATE: 0.18 VIDEO_10S_VIEW: 2 VIDEO_AVG_WATCH_TIME: 2507.75 VIDEO_MRC_VIEW: 20 VIDEO_START: 29 VIDEO_V50_WATCH_TIME: 10031 parameters: query_video_pin_metric_types: description: 'Metric types to get video data for, default is all. ' explode: false in: query name: metric_types required: false schema: items: enum: - IMPRESSION - SAVE - VIDEO_MRC_VIEW - VIDEO_AVG_WATCH_TIME - VIDEO_V50_WATCH_TIME - QUARTILE_95_PERCENT_VIEW - VIDEO_10S_VIEW - VIDEO_START - OUTBOUND_CLICK type: string type: array style: form query_campaign_ids_required: description: List of Campaign Ids to use to filter the results. in: query name: campaign_ids required: true schema: type: array items: type: string pattern: ^\d+$ maxLength: 18 minItems: 1 maxItems: 100 path_ad_account_id: name: ad_account_id description: Unique identifier of an ad account. in: path required: true schema: type: string pattern: ^\d+$ maxLength: 18 query_end_date: description: 'Metric report end date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days past start_date.' in: query name: end_date required: true schema: type: string format: date query_video_pin_sort_by: description: Specify sorting order for video metrics explode: false in: query name: sort_by required: true schema: enum: - IMPRESSION - SAVE - OUTBOUND_CLICK - VIDEO_MRC_VIEW - VIDEO_AVG_WATCH_TIME - VIDEO_V50_WATCH_TIME - QUARTILE_95_PERCENT_VIEW - VIDEO_10S_VIEW - VIDEO_START type: string query_ad_account_id: name: ad_account_id description: Unique identifier of an ad account. in: query schema: type: string pattern: ^\d+$ maxLength: 18 query_targeting_types: name: targeting_types description: Targeting type breakdowns for the report. The reporting per targeting type
is independent from each other. ["AGE_BUCKET_AND_GENDER"] is in BETA and not yet available to all users. required: true explode: false in: query schema: items: $ref: '#/components/schemas/AdsAnalyticsTargetingType' maxItems: 15 minItems: 1 type: array query_num_of_pins: name: num_of_pins in: query schema: type: integer minimum: 1 maximum: 50 default: 10 description: Number of pins to include, default is 10. Max is 50. example: 25 query_conversion_attribution_click_window_days: name: click_window_days in: query schema: type: integer enum: - 0 - 1 - 7 - 14 - 30 - 60 default: 30 description: Number of days to use as the conversion attribution window for a pin click action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. example: 1 query_conversion_attribution_conversion_report_time: description: 'The date by which the conversion metrics returned from this endpoint will be reported. There are two dates associated with a conversion event: the date that the user interacted with the ad, and the date that the user completed a conversion event.' example: TIME_OF_AD_ACTION in: query name: conversion_report_time schema: type: string enum: - TIME_OF_AD_ACTION - TIME_OF_CONVERSION default: TIME_OF_AD_ACTION query_from_claimed_content: description: Filter on Pins that match your claimed domain. in: query name: from_claimed_content required: false schema: default: BOTH enum: - OTHER - CLAIMED - BOTH type: string query_sort_by: description: Specify sorting order for metrics explode: false in: query name: sort_by required: true schema: enum: - ENGAGEMENT - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK - SAVE type: string query_app_types: description: Apps or devices to get data for, default is all. in: query name: app_types required: false schema: default: ALL enum: - ALL - MOBILE - TABLET - WEB type: string query_content_type: description: Filter to paid or organic data. Default is all. in: query name: content_type required: false schema: default: ALL enum: - ALL - PAID - ORGANIC type: string query_source: description: Filter to activity from Pins created and saved by your, or activity created and saved by others from your claimed accounts in: query name: source required: false schema: default: ALL enum: - ALL - YOUR_PINS - OTHER_PINS type: string query_granularity: description: TOTAL - metrics are aggregated over the specified date range.
DAY - metrics are broken down daily.
HOUR - metrics are broken down hourly.
WEEKLY - metrics are broken down weekly.
MONTHLY - metrics are broken down monthly example: DAY in: query name: granularity required: true schema: $ref: '#/components/schemas/Granularity' query_pin_analytics_metric_types: description: Pin metric types to get data for. Keep in mind this cannot have ALL if split_field is set to any value other than NO_SPLIT. explode: false in: query name: metric_types required: true schema: type: array items: oneOf: - description: Standard Pin metric types type: string enum: - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK - SAVE - SAVE_RATE - TOTAL_COMMENTS - TOTAL_REACTIONS - description: Video Pin metric types type: string enum: - IMPRESSION - OUTBOUND_CLICK - PIN_CLICK - SAVE - SAVE_RATE - VIDEO_MRC_VIEW - VIDEO_10S_VIEW - QUARTILE_95_PERCENT_VIEW - VIDEO_V50_WATCH_TIME - VIDEO_START - VIDEO_AVG_WATCH_TIME - TOTAL_COMMENTS - TOTAL_REACTIONS style: form query_product_group_ids_required: description: List of Product group Ids to use to filter the results. in: query name: product_group_ids required: true schema: type: array items: type: string pattern: ^\d+$ minItems: 1 maxItems: 100 query_pin_format: description: Pin formats to get data for, default is all. in: query name: pin_format required: false schema: default: ALL enum: - ALL - ORGANIC_IMAGE - ORGANIC_PRODUCT - ORGANIC_VIDEO - ADS_STANDARD - ADS_PRODUCT - ADS_VIDEO - ADS_IDEA - PRODUCT - REGULAR - VIDEO type: string query_columns: description: 'Columns to retrieve, encoded as a comma-separated string. **NOTE**: Any metrics defined as MICRO_DOLLARS returns a value based on the advertiser profile''s currency field. For USD,($1/1,000,000, or $0.000001 - one one-ten-thousandth of a cent). it''s microdollars. Otherwise, it''s in microunits of the advertiser''s currency.
For example, if the advertiser''s currency is GBP (British pound sterling), all MICRO_DOLLARS fields will be in GBP microunits (1/1,000,000 British pound).
If a column has no value, it may not be returned' explode: false in: query name: columns required: true schema: items: type: string description: Reporting columns for sync reporting endpoints example: TOTAL_CONVERSIONS enum: - SPEND_IN_MICRO_DOLLAR - PAID_IMPRESSION - SPEND_IN_DOLLAR - CPC_IN_MICRO_DOLLAR - ECPC_IN_MICRO_DOLLAR - ECPC_IN_DOLLAR - CTR - ECTR - CAMPAIGN_NAME - PIN_ID - TOTAL_ENGAGEMENT - ENGAGEMENT_1 - ENGAGEMENT_2 - ECPE_IN_DOLLAR - ENGAGEMENT_RATE - EENGAGEMENT_RATE - ECPM_IN_MICRO_DOLLAR - REPIN_RATE - CTR_2 - CAMPAIGN_ID - ADVERTISER_ID - AD_ACCOUNT_ID - PIN_PROMOTION_ID - AD_ID - AD_GROUP_ID - CAMPAIGN_ENTITY_STATUS - CAMPAIGN_OBJECTIVE_TYPE - CPM_IN_MICRO_DOLLAR - CPM_IN_DOLLAR - AD_GROUP_ENTITY_STATUS - ORDER_LINE_ID - ORDER_LINE_NAME - CLICKTHROUGH_1 - REPIN_1 - IMPRESSION_1 - IMPRESSION_1_GROSS - CLICKTHROUGH_1_GROSS - OUTBOUND_CLICK_1 - CLICKTHROUGH_2 - REPIN_2 - IMPRESSION_2 - OUTBOUND_CLICK_2 - TOTAL_CLICKTHROUGH - TOTAL_IMPRESSION - TOTAL_IMPRESSION_USER - TOTAL_IMPRESSION_FREQUENCY - COST_PER_OUTBOUND_CLICK_IN_DOLLAR - TOTAL_ENGAGEMENT_SIGNUP - TOTAL_ENGAGEMENT_CHECKOUT - TOTAL_ENGAGEMENT_LEAD - TOTAL_CLICK_SIGNUP - TOTAL_CLICK_CHECKOUT - TOTAL_CLICK_ADD_TO_CART - TOTAL_CLICK_LEAD - TOTAL_VIEW_SIGNUP - TOTAL_VIEW_CHECKOUT - TOTAL_VIEW_ADD_TO_CART - TOTAL_VIEW_LEAD - TOTAL_CONVERSIONS - TOTAL_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR - TOTAL_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR - TOTAL_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR - TOTAL_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_WEB_SESSIONS - WEB_SESSIONS_1 - WEB_SESSIONS_2 - CAMPAIGN_LIFETIME_SPEND_CAP - CAMPAIGN_DAILY_SPEND_CAP - TOTAL_PAGE_VISIT - TOTAL_SIGNUP - TOTAL_CHECKOUT - TOTAL_CUSTOM - TOTAL_LEAD - TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR - TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_CUSTOM_VALUE_IN_MICRO_DOLLAR - PAGE_VISIT_COST_PER_ACTION - PAGE_VISIT_ROAS - CHECKOUT_ROAS - CUSTOM_ROAS - VIDEO_MRC_VIEWS_1 - VIDEO_3SEC_VIEWS_2 - VIDEO_P100_COMPLETE_2 - VIDEO_P0_COMBINED_2 - VIDEO_P25_COMBINED_2 - VIDEO_P50_COMBINED_2 - VIDEO_P75_COMBINED_2 - VIDEO_P95_COMBINED_2 - VIDEO_MRC_VIEWS_2 - VIDEO_LENGTH - ECPV_IN_DOLLAR - ECPCV_IN_DOLLAR - ECPCV_P95_IN_DOLLAR - TOTAL_VIDEO_3SEC_VIEWS - TOTAL_VIDEO_P100_COMPLETE - TOTAL_VIDEO_P0_COMBINED - TOTAL_VIDEO_P25_COMBINED - TOTAL_VIDEO_P50_COMBINED - TOTAL_VIDEO_P75_COMBINED - TOTAL_VIDEO_P95_COMBINED - TOTAL_VIDEO_MRC_VIEWS - TOTAL_VIDEO_AVG_WATCHTIME_IN_SECOND - TOTAL_REPIN_RATE - WEB_CHECKOUT_COST_PER_ACTION - WEB_CHECKOUT_ROAS - TOTAL_WEB_CHECKOUT - TOTAL_WEB_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_WEB_CLICK_CHECKOUT - TOTAL_WEB_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_WEB_ENGAGEMENT_CHECKOUT - TOTAL_WEB_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR - TOTAL_WEB_VIEW_CHECKOUT - TOTAL_WEB_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR - INAPP_CHECKOUT_COST_PER_ACTION - TOTAL_OFFLINE_CHECKOUT - IDEA_PIN_PRODUCT_TAG_VISIT_1 - IDEA_PIN_PRODUCT_TAG_VISIT_2 - TOTAL_IDEA_PIN_PRODUCT_TAG_VISIT - LEADS - COST_PER_LEAD - QUIZ_COMPLETED - QUIZ_COMPLETION_RATE - SHOWCASE_PIN_CLICKTHROUGH - SHOWCASE_SUBPAGE_CLICKTHROUGH - SHOWCASE_SUBPIN_CLICKTHROUGH - SHOWCASE_SUBPAGE_IMPRESSION - SHOWCASE_SUBPIN_IMPRESSION - SHOWCASE_SUBPAGE_SWIPE_LEFT - SHOWCASE_SUBPAGE_SWIPE_RIGHT - SHOWCASE_SUBPIN_SWIPE_LEFT - SHOWCASE_SUBPIN_SWIPE_RIGHT - SHOWCASE_SUBPAGE_REPIN - SHOWCASE_SUBPIN_REPIN - SHOWCASE_SUBPAGE_CLOSEUP - SHOWCASE_CARD_THUMBNAIL_SWIPE_FORWARD - SHOWCASE_CARD_THUMBNAIL_SWIPE_BACKWARD - SHOWCASE_AVERAGE_SUBPAGE_CLOSEUP_PER_SESSION - TOTAL_CHECKOUT_CONVERSION_RATE - TOTAL_VIEW_CATEGORY_CONVERSION_RATE - TOTAL_ADD_TO_CART_CONVERSION_RATE - TOTAL_SIGNUP_CONVERSION_RATE - TOTAL_PAGE_VISIT_CONVERSION_RATE - TOTAL_LEAD_CONVERSION_RATE - TOTAL_SEARCH_CONVERSION_RATE - TOTAL_WATCH_VIDEO_CONVERSION_RATE - TOTAL_UNKNOWN_CONVERSION_RATE - TOTAL_CUSTOM_CONVERSION_RATE type: array query_start_date: description: 'Metric report start date (UTC). Format: YYYY-MM-DD. Cannot be more than 90 days back from today.' in: query name: start_date required: true schema: type: string format: date query_created_in_last_n_days: name: created_in_last_n_days in: query schema: type: integer enum: - 30 description: Get metrics for pins created in the last "n" days. example: 30 query_ad_group_ids_required: description: List of Ad group Ids to use to filter the results. in: query name: ad_group_ids required: true schema: type: array items: type: string pattern: ^\d+$ maxLength: 18 minItems: 1 maxItems: 100 query_conversion_attribution_engagement_window_days: name: engagement_window_days in: query description: Number of days to use as the conversion attribution window for an engagement action. Engagements include saves, closeups, link clicks, and carousel card swipes. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `30` days. schema: type: integer enum: - 0 - 1 - 7 - 14 - 30 - 60 default: 30 query_ad_ids_required: description: List of Ad Ids to use to filter the results. in: query name: ad_ids required: true schema: type: array items: type: string pattern: ^\d+$ minItems: 1 maxItems: 100 query_split_field_pins: description: How to split the data into groups. Not including this param means data won't be split. required: false in: query explode: false name: split_field schema: default: NO_SPLIT enum: - NO_SPLIT - APP_TYPE type: string path_pin_id: name: pin_id description: Unique identifier of a Pin. in: path required: true schema: type: string query_conversion_attribution_view_window_days: name: view_window_days in: query description: Number of days to use as the conversion attribution window for a view action. Applies to Pinterest Tag conversion metrics. Prior conversion tags use their defined attribution windows. If not specified, defaults to `1` day. schema: type: integer enum: - 0 - 1 - 7 - 14 - 30 - 60 default: 1 query_split_field_user_account: description: How to split the data into groups. Not including this param means data won't be split. required: false in: query explode: false name: split_field schema: default: NO_SPLIT enum: - NO_SPLIT - APP_TYPE - OWNED_CONTENT - SOURCE - PIN_FORMAT type: string query_attribution_types: name: attribution_types description: List of types of attribution for the conversion report required: false explode: false in: query schema: $ref: '#/components/schemas/ConversionReportAttributionType' query_metric_types: description: 'Metric types to get data for, default is all. ' explode: false in: query name: metric_types required: false schema: items: enum: - ENGAGEMENT - ENGAGEMENT_RATE - IMPRESSION - OUTBOUND_CLICK - OUTBOUND_CLICK_RATE - PIN_CLICK - PIN_CLICK_RATE - SAVE - SAVE_RATE type: string type: array style: form securitySchemes: pinterest_oauth2: type: oauth2 flows: authorizationCode: authorizationUrl: https://www.pinterest.com/oauth/ tokenUrl: https://api.pinterest.com/v5/oauth/token scopes: ads:read: See all of your advertising data, including ads, ad groups, campaigns etc. ads:write: Create, update, or delete ads, ad groups, campaigns etc. billing:read: See all of your billing data, billing profile, etc. billing:write: Create, update, or delete billing data, billing profiles, etc. biz_access:read: See business access data biz_access:write: Create, update, or delete business access data boards:read: See your public boards, including group boards you join boards:read_secret: See your secret boards boards:write: Create, update, or delete your public boards boards:write_secret: Create, update, or delete your secret boards catalogs:read: See all of your catalogs data catalogs:write: Create, update, or delete your catalogs data pins:read: See your public Pins pins:read_secret: See your secret Pins pins:write: Create, update, or delete your public Pins pins:write_secret: Create, update, or delete your secret Pins user_accounts:read: See your user accounts and followers user_accounts:write: Update your user accounts and followers conversion_token: type: http scheme: bearer description: This security scheme only applies to the conversion events endpoint (POST /ad_accounts/{ad_account_id}/events). This endpoint requires a bearer token generated via Ads Manager (ads.pinterest.com). basic: type: http scheme: basic x-tagGroups: - name: Pin and Boards tags: - pins - boards - media - aggregated_comments - aggregated_pin_data - user_account - name: Campaign Management tags: - ad_accounts - campaigns - ad_groups - ads - product_group_promotions - bulk - name: Targeting tags: - audiences - customer_lists - keywords - targeting_template - audience_insights - audience_sharing - name: Ad Formats tags: - lead_forms - lead_ads - leads_export - name: Billing tags: - billing - order_lines - terms_of_service - name: Business Access tags: - business_access_assets - business_access_invite - business_access_relationships - name: Conversions tags: - conversion_events - conversion_tags - name: Others tags: - integrations - oauth - resources - search - terms - name: Shopping tags: - catalogs - name: Deprecated tags: - product_groups