openapi: 3.0.3 info: version: 5.13.0 title: Pinterest Campaigns 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: Campaigns paths: /ad_accounts/{ad_account_id}/campaigns: get: summary: List campaigns description: 'Get a list of the campaigns 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.' operationId: campaigns/list security: - pinterest_oauth2: - ads:read x-ratelimit-category: ads_read x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' - $ref: '#/components/parameters/query_campaign_ids' - $ref: '#/components/parameters/query_entity_statuses' - $ref: '#/components/parameters/query_page_size' - $ref: '#/components/parameters/query_order' - $ref: '#/components/parameters/query_bookmark' responses: '200': content: application/json: schema: allOf: - $ref: '#/components/schemas/Paginated' - type: object properties: items: type: array items: $ref: '#/components/schemas/CampaignResponse' description: Success '400': description: Invalid ad account campaign parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: Invalid ad account campaign parameters. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Campaigns post: summary: Create campaigns description: "Create multiple new campaigns. Every campaign has its own campaign_id and houses one or more ad groups, which contain one or more ads.\nFor more, see Set up your campaign.

\nNote:\n- The values for 'lifetime_spend_cap' and 'daily_spend_cap' are microcurrency amounts based on the currency field set in the advertiser's profile. (e.g. USD)

Microcurrency is used to track very small transactions, based on the currency set in the advertisers profile.

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertisers profile.

Equivalency equations, using dollars as an example currency:

$1 = 1,000,000 microdollars
1 microdollar = $0.000001

To convert between currency and microcurrency, using dollars as an example currency:

To convert dollars to microdollars, mutiply dollars by 1,000,000
To convert microdollars to dollars, divide microdollars by 1,000,000

" tags: - Campaigns operationId: campaigns/create security: - pinterest_oauth2: - ads:write x-ratelimit-category: ads_write x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' requestBody: description: Array of campaigns. required: true content: application/json: schema: type: array maxItems: 30 minItems: 1 items: $ref: '#/components/schemas/CampaignCreateRequest' responses: '200': description: response content: application/json: schema: $ref: '#/components/schemas/CampaignCreateResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' patch: summary: Update campaigns description: "Update multiple ad campaigns based on campaign_ids.

\nNote:

\n -

The values for 'lifetime_spend_cap' and 'daily_spend_cap' are microcurrency amounts based on the currency field set in the advertiser's profile. (e.g. USD)

Microcurrency is used to track very small transactions, based on the currency set in the advertisers profile.

A microcurrency unit is 10^(-6) of the standard unit of currency selected in the advertiser s profile.

Equivalency equations, using dollars as an example currency:

$1 = 1,000,000 microdollars
1 microdollar = $0.000001

To convert between currency and microcurrency, using dollars as an example currency:

To convert dollars to microdollars, mutiply dollars by 1,000,000
To convert microdollars to dollars, divide microdollars by 1,000,000

" tags: - Campaigns operationId: campaigns/update security: - pinterest_oauth2: - ads:write x-ratelimit-category: ads_write x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' requestBody: description: Array of campaigns. required: true content: application/json: schema: type: array maxItems: 30 minItems: 1 items: $ref: '#/components/schemas/CampaignUpdateRequest' responses: '200': description: response content: application/json: schema: $ref: '#/components/schemas/CampaignUpdateResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' /ad_accounts/{ad_account_id}/campaigns/analytics: get: summary: Get campaign analytics description: 'Get analytics for the specified campaigns 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: campaigns/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_campaign_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/CampaignsAnalyticsResponse' description: Success '400': description: Invalid ad account campaign analytics parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: 400 message: Invalid ad account campaign analytics parameters. default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Campaigns /ad_accounts/{ad_account_id}/campaigns/targeting_analytics: get: summary: Get targeting analytics for campaigns description: 'Get targeting analytics for one or more campaigns. For the requested account 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: campaign_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_campaign_ids_required' - $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: - Campaigns /ad_accounts/{ad_account_id}/campaigns/{campaign_id}: get: summary: Get campaign description: Get a specific campaign given the campaign ID. operationId: campaigns/get security: - pinterest_oauth2: - ads:read x-ratelimit-category: ads_read x-sandbox: enabled parameters: - $ref: '#/components/parameters/path_ad_account_id' - $ref: '#/components/parameters/path_campaign_id' responses: '200': description: Success content: application/json: schema: $ref: '#/components/schemas/CampaignResponse' default: description: Unexpected error content: application/json: schema: $ref: '#/components/schemas/Error' tags: - Campaigns components: schemas: CampaignCreateCommon: type: object allOf: - $ref: '#/components/schemas/CampaignCommon' - type: object properties: status: type: string default: ACTIVE allOf: - $ref: '#/components/schemas/EntityStatus' is_flexible_daily_budgets: type: boolean default: false allOf: - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' default_ad_group_budget_in_micro_currency: type: integer description: When transitioning from campaign budget optimization to non-campaign budget optimization, the default_ad_group_budget_in_micro_currency will propagate to each child ad groups daily budget. Unit is micro currency of the associated advertiser account. example: 0 nullable: true is_automated_campaign: type: boolean default: false allOf: - $ref: '#/components/schemas/CampaignIsAutomatedCampaign' EntityStatus: type: string description: Entity status example: ACTIVE enum: - ACTIVE - PAUSED - ARCHIVED - DRAFT - DELETED_DRAFT Error: title: Error type: object properties: code: type: integer message: type: string required: - code - message Exception: title: Generic exception class to be used within schemas type: object properties: code: type: integer example: 2 description: Exception error code. message: type: string example: Advertiser not found. description: Exception message. ObjectiveType: type: string description: Campaign objective type. If set as one of ["AWARENESS", "CONSIDERATION", "WEB_CONVERSION", "CATALOG_SALES"] the campaign is considered as a Campaign Budget Optimization (CBO) campaign, meaning budget needs to be set at the campaign level rather than at the ad group level. ["WEB_SESSIONS"] is DEPRECATED. For update, only draft campaigns may update objective type. enum: - AWARENESS - CONSIDERATION - VIDEO_VIEW - WEB_CONVERSION - CATALOG_SALES - WEB_SESSIONS CampaignResponse: type: object allOf: - $ref: '#/components/schemas/CampaignId' - $ref: '#/components/schemas/CampaignCommon' - type: object properties: objective_type: $ref: '#/components/schemas/ObjectiveType' created_time: type: integer description: Campaign creation time. Unix timestamp in seconds. example: 1432744744 updated_time: type: integer description: UTC timestamp. Last update time. example: 1432744744 type: type: string description: Always "campaign". example: campaign is_flexible_daily_budgets: type: boolean description: Determines if a campaign has flexible daily budgets setup. example: true nullable: true is_campaign_budget_optimization: type: boolean description: Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared. example: true nullable: true CampaignCreateResponseItem: type: object properties: data: $ref: '#/components/schemas/CampaignCreateResponseData' exceptions: type: array items: $ref: '#/components/schemas/Exception' CampaignIsFlexibleDailyBudgets: type: boolean description: Determine if a campaign has flexible daily budgets setup. example: true default: false CampaignCreateResponse: type: object properties: items: type: array items: $ref: '#/components/schemas/CampaignCreateResponseItem' 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 Paginated: type: object properties: items: type: array items: type: object bookmark: type: string nullable: true required: - items CampaignUpdateResponse: type: object allOf: - $ref: '#/components/schemas/CampaignCreateResponse' CampaignIsAutomatedCampaign: type: boolean description: Specifies whether the campaign was created in the automated campaign flow example: true default: false CampaignUpdateRequest: type: object allOf: - $ref: '#/components/schemas/CampaignId' - $ref: '#/components/schemas/CampaignCommon' - $ref: '#/components/schemas/CampaignCreateCommon' - type: object properties: is_campaign_budget_optimization: type: boolean nullable: true allOf: - $ref: '#/components/schemas/CampaignIsCampaignBudgetOptimization' is_flexible_daily_budgets: type: boolean nullable: true allOf: - $ref: '#/components/schemas/CampaignIsFlexibleDailyBudgets' is_automated_campaign: type: boolean nullable: true allOf: - $ref: '#/components/schemas/CampaignIsAutomatedCampaign' status: type: string nullable: true allOf: - $ref: '#/components/schemas/EntityStatus' objective_type: type: string nullable: true allOf: - $ref: '#/components/schemas/ObjectiveType' required: - id - ad_account_id CampaignCommon: type: object description: Campaign Data properties: ad_account_id: description: Campaign's Advertiser ID. If you want to create a campaign in a Business Account shared account you need to specify the Business Access advertiser ID in both the query path param as well as the request body schema. example: '549755885175' type: string pattern: ^\d+$ name: type: string description: Campaign name. example: ACME Tools status: type: string allOf: - $ref: '#/components/schemas/EntityStatus' lifetime_spend_cap: description: Campaign total spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "daily_spend_cap" cannot be set at the same time. example: 1432744744 type: integer nullable: true daily_spend_cap: description: Campaign daily spending cap. Required for Campaign Budget Optimization (CBO) campaigns. This and "lifetime_spend_cap" cannot be set at the same time. example: 1432744744 type: integer nullable: true order_line_id: description: Order line ID that appears on the invoice. example: '549755885175' type: string pattern: ^\d+$ nullable: true tracking_urls: type: object nullable: true allOf: - $ref: '#/components/schemas/TrackingUrls' start_time: type: integer description: Campaign start time. Unix timestamp in seconds. Only used for Campaign Budget Optimization (CBO) campaigns. example: 1580865126 nullable: true end_time: type: integer description: Campaign end time. Unix timestamp in seconds. Only used for Campaign Budget Optimization (CBO) campaigns. example: 1644023526 nullable: true summary_status: type: string allOf: - $ref: '#/components/schemas/CampaignSummaryStatus' CampaignIsCampaignBudgetOptimization: type: boolean description: Determines if a campaign automatically generate ad-group level budgets given a campaign budget to maximize campaign outcome. When transitioning from non-cbo to cbo, all previous child ad group budget will be cleared. example: true default: false CampaignCreateRequest: type: object allOf: - $ref: '#/components/schemas/CampaignCreateCommon' - type: object properties: objective_type: $ref: '#/components/schemas/ObjectiveType' required: - name - objective_type - ad_account_id TrackingUrls: description: Third-party tracking URLs. Up to three tracking URLs - with a max length of 2,000 - are supported for each event type. Tracking URLs set at the ad group or ad level can override those set at the campaign level. For more information, see Third-party and dynamic tracking. example: impression: - URL1 - URL2 click: - URL1 - URL2 engagement: - URL1 - URL2 buyable_button: - URL1 - URL2 audience_verification: - URL1 - URL2 type: object nullable: true properties: impression: type: array items: type: string click: type: array items: type: string engagement: type: array items: type: string buyable_button: type: array items: type: string audience_verification: type: array items: type: string ConversionReportAttributionType: type: string description: Attribution type. Refers to the Pinterest Tag endpoints example: INDIVIDUAL enum: - INDIVIDUAL - HOUSEHOLD CampaignId: properties: id: description: Campaign ID. example: '549755885175' type: string pattern: ^\d+$ type: object 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 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 CampaignCreateResponseData: type: object allOf: - $ref: '#/components/schemas/CampaignCreateCommon' - $ref: '#/components/schemas/CampaignResponse' - type: object properties: objective_type: $ref: '#/components/schemas/ObjectiveType' CampaignSummaryStatus: type: string description: Summary status for campaign example: RUNNING enum: - RUNNING - PAUSED - NOT_STARTED - COMPLETED - ADVERTISER_DISABLED - ARCHIVED - DRAFT - DELETED_DRAFT Granularity: type: string description: Granularity enum: - TOTAL - DAY - HOUR - WEEK - MONTH parameters: 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_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_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_page_size: name: page_size description: Maximum number of items to include in a single page of the response. See documentation on Pagination for more information. in: query required: false schema: type: integer minimum: 1 maximum: 250 default: 25 query_bookmark: name: bookmark description: Cursor used to fetch the next page of items in: query required: false schema: 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' path_campaign_id: name: campaign_id description: Campaign ID, must be associated with the ad account ID provided in the path. in: path required: true schema: type: string pattern: ^\d+$ maxLength: 18 query_order: description: 'The order in which to sort the items returned: ASCENDING or DESCENDING by ID. Note that higher-value IDs are associated with more-recently added items.' in: query name: order required: false schema: type: string example: ASCENDING enum: - ASCENDING - DESCENDING 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_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_entity_statuses: in: query name: entity_statuses required: false description: Entity status schema: type: array items: type: string example: ACTIVE enum: - ACTIVE - PAUSED - ARCHIVED - DRAFT - DELETED_DRAFT default: - ACTIVE - PAUSED 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_campaign_ids: description: List of Campaign Ids to use to filter the results. in: query name: campaign_ids required: false schema: type: array items: type: string pattern: ^\d+$ maxLength: 18 minItems: 1 maxItems: 100 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' 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