Ads reporting

Pinterest provides many metrics for evaluating advertisers, campaigns, ad groups, keywords, and ads.

Pinterest Analytics helps you understand your overall presence on Pinterest. Learn more.
Via this API, we provide 90+ metrics for your organic Pins and ads. This guide will help you understand how to pull analytics for ads and the definition of each metric.

Using different reporting methods

The Pinterest API provides multiple ways to generate reports and analytical data. Consider your business need or specific use case when selecting a method:

API reporting methods
Method	Use cases	Caveats	Endpoints
Synchronous or sync Pinterest returns requested data immediately in the response to your API call.	Quick, small data requests such as: The current day's ad spend A single campaign's stats Real-time dashboards or UI widgets that display up-to-the-minute metrics and require instant feedback. Testing and debugging to verify that your request and data formatting are correct.	Limits on the amount of data you can request, such as row or date range restrictions. Large requests may fail or be truncated. Timeout risk if the query takes too long due to data volume or complexity, resulting in errors or incomplete data. Resource strain and exceeded rate limits, especially with multiple or frequent sync requests. Unsuitability for automation or scheduled, large-scale reporting.	GET Get ad account analytics GET Get targeting analytics for an ad account GET Get campaign analytics GET Get targeting analytics for campaigns GET Get ad group analytics GET Get targeting analytics for ad groups GET Get ad analytics GET Get targeting analytics for ads GET Get product group analytics GET Get product group analytics
Asynchronous or async Pinterest processes your request in the background and provides a URL to download the data once it is ready.	Large or complex datasets that may take time to process, such as all campaign data for the past year. Scheduling or automation, such as for nightly, weekly, or monthly reporting jobs that can run in the background and be retrieved when ready. Avoiding timeouts and failures when data volume or processing time could exceed HTTP timeout limits.	Operational complexity: Managing job IDs Polling for status Handling callbacks or retries Delayed results, as report generation can take minutes or longer for large jobs. Job expiry, where some platforms only retain completed reports available for a limited time, requiring you to download them promptly. Error handling for job failures, partial data, or incomplete jobs.	To request a report and specify the information in it: POST Create async request for an account analytics report To download the report when it is ready: GET Get the account analytics report created by the async call
Bulk Pinterest provides entire datasets, such as all ad performance data for an account, in a single or batched file, sometimes in compressed formats.	Data warehousing and analytics, when you need to ingest large amounts of historical or raw data. Data export for migration, backup, or compliance purposes. Advanced, custom analysis on large datasets, for which multiple, smaller API calls would be impractical.	Very large files that may be hundreds of megabytes or more, requiring significant bandwidth, storage, and processing power. Potential data staleness, as bulk data is often updated less frequently and may not reflect the most recent activity. Parsing and processing time and overhead, such as the need for Extract, Transform, Load (ETL) pipelines. Limited filtering and customization, where you get all the data, even if you only need a subset. Security and compliance concerns, where handling large exports of sensitive data increases your responsibility for data protection. Rate limits causing timeouts with large datasets, which could necessitate measures such as chunking requests by date.	To request an asynchronous bulk report: POST Get advertiser entities in bulk To download the bulk report when it is ready: GET Download advertiser entities in bulk

Mapping API metrics to Ads Manager

To find the definition of metrics or map metrics from the API to Ads Manager, use

GET

Get available metrics' definitions

. The returned

display_name

attribute for each metric shows its name in Ads Manager.

The response will return a list of objects, each representing a metric. The object properties are:

name
: the name used for the metric in the API
category
: whether the metric is organic or ads related
definition
: description of the metric
display_name
: the name of the metric in Ads Manager. This field may be blank if the display name is the same as what's used in the API.

In the response example below,

CLICKTHROUGH_2

is defined as the total number of Pin clicks from ads saved to another person's board. This metric is displayed in the Ads Manager as

Earned Pin clicks


{
  "name": "CLICKTHROUGH_2",
  "category": "ADS",
  "definition": "Total number of Pin clicks from ads saved to another person's board",
  "display_name": "Earned Pin clicks"
}

Concepts to understand with metric names

Metric names ending in
_1
represent first order ad events. For example, CLICKTHROUGH_1 is the number of Pin clicks on an ad.
Metric names ending in
_2
represent downstream, earned events. These are actions taken on saved ads. Advertisers are not billed for earned activity.
SPEND_IN_MICRO_DOLLAR
represents the spend in the micro currency (millionth of a currency unit) of the advertiser.
Metrics that begin with TOTAL refer to conversion data.
TOTAL_CONVERSIONS
is the total number of conversions for the requested reporting period. If you are passing order quantity and order value in Pinterest Tag conversion events, these totals will show in
TOTAL_CONVERSIONS_QUANTITY
and
TOTAL_CONVERSIONS_VALUE_IN_MICRO_DOLLAR
.
Total conversions, quantity, and value are further broken out by different conversion types you may be tracking, as well as attribution types. For example:
TOTAL_CLICK_CHECKOUT
is the total of click-through conversions of type
checkout
.
TOTAL_VIEW_CHECKOUT
is the total of view-through conversions of type
checkout
.
TOTAL_ENGAGEMENT_CHECKOUT_QUANTITY
is the total order quantity for engagement-through conversions of type
checkout
.
TOTAL_VIEW_ADD_TO_CART_VALUE_IN_MICRO_DOLLAR
is the total order value of view-through conversions of type
add to cart
.
Cross-device conversion metrics are available through the fields that have ACTION in their name. For example:
TOTAL_VIEW_CATEGORY_MOBILE_ACTION_TO_DESKTOP_CONVERSION
is the total for conversions of type
view category
where the attributed ad event occurred on mobile and the conversion event occurred on desktop.
TOTAL_ADD_TO_CART_MOBILE_ACTION_TO_DESKTOP_CONVERSION
is the total for conversions of type
add to cart
where the attributed ad event occurred on mobile and the conversion event occurred on desktop.

Using report templates

We added the ability to pull ads analytics using report templates to make it easier to replicate reports created in Ads Manager:

Users who prefer to set up a report template in Ads Manager are now able to download saved reports through the API

Create a custom report in Ads Manager

First, create a custom report in Ads Manager.

Log into your Pinterest business account.
Navigate to ads.pinterest.com.
Click Ads or Export above the reporting table, then select Custom reports.
Click Create new report at the top-right of your screen.
Edit the fields in Report details.
1. Under Template, make sure that Custom is selected from the dropdown.
2. Add a Name for your report.
3. Under Visibility, select who you'd like to be able to see your report.
  1. Set to Visible for ad account which means anyone with access to reporting for that ad account can see the template.
Edit the fields in Data filters.
1. Select from the predefined list, or add and save advanced filters to create a customized data view.
Edit the fields in Columns.
1. Search for a column by name in the search bar.
2. Find a column by clicking the directional chevron right icon to open a specific group.
3. Remove a column by clicking the x circle icon next to its name.
4. Reorder columns using drag and drop under Selected columns.
Edit the fields in Scheduling and timeframe. 5. Under Report frequency select One-time only. 6. Select a Timeframe that you'd like to see reporting for.
Select Run & save.

View saved report templates

With a saved report template in Ads Manager, developers can then use the

GET

List templates

endpoint to see an advertiser's saved templates.

Use

POST

Create async request for an analytics report using a template

to request the report. Users are able to change the start date, end date, and granularity of the saved template through the endpoint.

Changes to the report timeframe through this endpoint will not be saved to the template.

With a generated report, use the
GET
Get the account analytics report created by the async call
endpoint to download the report.
Users who prefer to generate ad reports entirely through the API can continue to use:
- POST
  Create async request for an account analytics report
- GET
  Get the account analytics report created by the async call

Reporting on ad spend for Premiere Spotlight campaigns

For Premiere Spotlight campaigns, which run one day in the United States and one to three days elsewhere, wait 24 to 48 hours after your campaign ends before you review the spend and performance metrics.

Reporting for ad spend for Premiere Spotlight campaigns is based on Coordinated Universal Time (UTC) time zone, not your local time zone. The total spend for a campaign is spread out evenly over each hour or a 24-hour day, not attributed to the exact hour it happened in your local time.

Because of the time zone difference, the spend for a single day in your local time might appear split between two different days in the report. For example, if a campaign runs on a Monday, the some of the spend may appear as having occurred on the adjacent Sunday or Tuesday.

Pulling analytics

Get analytics asynchronously

If you need to get analytics for a large number of campaigns, ad groups, or ads, or to generate historical data across a wide date range, use the asynchronous analytics endpoints:

Request
POST
Create async request for an account analytics report
in JSON or CSV
Then
GET
Get the account analytics report created by the async call
created by the request in #1

Get analytics synchronously

If you need to get analytics for a small number of campaigns, ad groups, or ads, use these endpoints to request them synchronously:

Provide these parameters:

ad_account_id
start_date
and
end_date
for your analytics
columns
: metrics to include in the response. Each column will include a metric.
the level of
granularity
e.g. report metrics by month, week, day, hour, or total
the number of days to use as an attribution window for each type of user action e.g.
click_window_days
,
engagement_window_days
,
view_window_days
the
conversion_report_time
to use as the basis for the report -- that is, report based on the day the user interacted with your ad, or the day the conversion event took place

Targeting analytics

Some endpoints take a

targeting_spec

object parameter, which allows the advertiser to specify target audience filters. Learn more about targeting.

Once the campaign runs, you can get analytics and break them down by targeting filters, using these endpoints:

Targeting analytics are not available for product groups.

API request

ad_account_id
IDs of the entities -
campaign_ids
,
ad_group_ids
, or
ad_ids
start_date
end_date
targeting_types
: KEYWORD, APPTYPE, GENDER, LOCATION, PLACEMENT, etc.
columns
: metrics to include
granularity
: month, week, day, or hour, or simply a total over the specified range.
click_window_days
,
engagement_window_days
,
view_window_days
: conversion attribution windows for Pin clicks, engagement actions, or view actions.
conversion_report_time
: whether conversions should be reported based on the point at which the user performed the action in question, or the point at which the user completed the conversion event.
attribution_types
: type of attribution for conversion report:
INDIVIDUAL
or
HOUSEHOLD
.

Analytics by metro zone

To see your campaign, ad group, and ads analytics by metro zone/code, specify

targeting_type

= 'LOCATION'. The response will include metro code and the associated analytics, such as ad spend, impressions, etc. You do not need to specify targeting by metro zones/codes when creating ad groups in order to get analytics by metro zones/codes.

If the ad was not seen by anyone in a certain metro zone, that code will not be included in the API call response.

Example Response


{
  "targeting_type": "LOCATION",
  "targeting_value": "500",
  "metrics": {
    "AD_GROUP_ID": "1234567891234",
    "SPEND_IN_MICRO_DOLLAR": 224113022
  }
}

Get all available codes and zones

To see a complete and current list of country and metro codes that you can use, call

GET

Get targeting options

Add the

LOCATION

enum to the request to see all possible metropolitan and country codes:


curl --location --request GET 'https://api.pinterest.com/resources/targeting/LOCATION?' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <Add your token here>' \

Excerpts of the response:


    ...
    "500": "U.S.: Portland-Auburn",
    "501": "U.S.: New York",
    "502": "U.S.: Binghamton",
    "503": "U.S.: Macon",
    "504": "U.S.: Philadelphia",
    "505": "U.S.: Detroit",
    "506": "U.S.: Boston (Manchester)",
    "507": "U.S.: Savannah",
    ...
    "AR": "Argentina",
    "AU": "Australia",
    "AT": "Austria",
    "BE": "Belgium",
    "BR": "Brazil",
    "CA": "Canada",
    "CL": "Chile",
    ...

Add the

GEO

enum to see regions within United States, US territories, and other countries:


curl --location --request GET 'https://api.pinterest.com/resources/targeting/GEO?' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer <Add your token here>' \

Excerpts of the response:


        ...
        "547": {
          "country": "US",
          "name": "Toledo"
        },
        "548": {
          "country": "US",
          "name": "West Palm Beach-Ft. Pierce"
        },
        "549": {
          "country": "US",
          "name": "Watertown"
        },
        ...
        "IT": {
          "country": "Italy",
          "regions": {
            "IT-23": {
              "country": "IT",
              "name": "Province of valle d'aosta"
        },
             "IT-36": {
               "country": "IT",
               "name": "Friuli Venezia Giulia"
        },
        ...
        "UST": {
          "country": "U.S. Territories",
          "regions": {
            "US-PR": {
              "country": "UST",
              "name": "Puerto Rico"
        },
        "US-VI": {
          "country": "UST",
          "name": "Virgin Islands"
          ...

Get metrics ready state

Use

GET

Get metrics ready state

to learn whether conversion or non-conversion metrics are finalized and ready to query. This request will return

true

if the metrics are ready to be used in reports, and

false

if they are not.

Audience Insights

Audience Insights reveal what your existing and potential customers are interested in, based on their behavior on Pinterest. These insights are powered by the actions people take on Pinterest, like searches and saves. You may temporarily see some differences in your insights across platforms. Learn more about Audience Insights.

Use

GET

Get audience insights

to get insights on the advertiser's audience. By default, the insights are only shown for the audience that's engaged with the advertiser's content in the last 30 days. It's not possible to customize the date range.

Request

ad_account_id
of the advertiser
audience_insight_type
options:
YOUR_TOTAL_AUDIENCE
: the total number of people who have seen or engaged with the advertiser's Pins in the last 30 days. This includes Pins the advertiser created or saved (both organic and ads) as well as any Pins that have been saved from the advertiser's claimed website or claimed accounts.
YOUR_ENGAGED_AUDIENCE
: the number of people who have engaged with the advertiser's Pins in the last 30 days.
PINTEREST_TOTAL_AUDIENCE
: the total number of people who have seen or engaged with Pins across Pinterest in the last 30 days.

Response

The response will return insights for 3 types of audiences: the ad account's engaged audience on Pinterest, the ad account's total audience on Pinterest and Pinterest's total audience. Returned attributes include:

categories
: array of objects, representing the most popular categories and related interests for this audience. Each interest object will contain the following attributes:
- key
  : unique interest ID
- name
  : interest name e.g.
  travel
- ratio
  : % of audience that is interest in this category or interest
- index
  : interest's affinity index. Affinity indicates the strength of your audience's interest in a particular category compared to the average person on Pinterest. A high affinity indicates that this portion of your audience has a strong likelihood of engaging with content related to this interest.
- id
  : interest ID
demographics
: an object of audience demographics
- ages
  : an array of objects that represents the age distribution of the audience
  - key
    : unique key for age group
  - name
    : display name for age group, e.g.
    18-24
    
    25-34
    etc.
  - ratio
    : % of the audience, expressed as a ratio. Ratios will sum to 1 (100%).
- genders
  : an array of objects that represents the gender distribution of the audience
  - key
    : unique key for gender
  - name
    : display name for gender, e.g.
    Male
    
    Female
    
    Unspecified & custom
  - ratio
    : % of the audience belonging to that gender category, expressed as a ratio. Ratios will sum to 1 (100%).
- devices
  : an array of objects that represents the devices used by the audience
  - key
    : unique key for device
  - name
    : display name for device, e.g.
    iPhone
    
    iPad
    
    Android Mobile
    etc.
  - ratio
    : % of the audience using the device, expressed as a ratio. Ratios will not sum to 1 (100%).
- metros
  : array of objects that represent the top metro areas for this audience
  - key
    : unique key for metro area
  - name
    : display name for metro area e.g.
    Los Angeles
    
    New York
    etc.
  - ratio
    : % of the audience located in the metro area, expressed as a ratio. Ratios will not sum to 1 (100%).
- countries
  : array of objects that represent the top countries for this audience
  - key
    : unique key for country
  - name
    : display name for country, e.g.
    United States
    
    Mexico
    etc.
  - ratio
    : % of the audience located in the country, expressed as a ratio. Ratios will sum to 1 (100%).
type
: the type of audience for which the insights are returned
date
: when the audience was last updated
size
: the size of the audience
size_is_upper_bound
: indicates whether the audience size has been rounded up to the next highest upper boundary. Enum:
true
or
false
.

Was this page helpful?

API reporting methods

Method

Use cases

Caveats

Endpoints

Synchronous or sync

Pinterest returns requested data immediately in the response to your API call.

Quick, small data requests such as:

The current day's ad spend
A single campaign's stats

Real-time dashboards or UI widgets that display up-to-the-minute metrics and require instant feedback.

Testing and debugging to verify that your request and data formatting are correct.

Limits on the amount of data you can request, such as row or date range restrictions. Large requests may fail or be truncated.

Timeout risk if the query takes too long due to data volume or complexity, resulting in errors or incomplete data.

Resource strain and exceeded rate limits, especially with multiple or frequent sync requests.

Unsuitability for automation or scheduled, large-scale reporting.

GET

Get ad account analytics

GET

Get targeting analytics for an ad account

GET

Get campaign analytics

GET

Get targeting analytics for campaigns

GET

Get ad group analytics

GET

Get targeting analytics for ad groups

GET

Get ad analytics

GET

Get targeting analytics for ads

GET

Get product group analytics

GET

Get product group analytics

Asynchronous or async

Pinterest processes your request in the background and provides a URL to download the data once it is ready.

Large or complex datasets that may take time to process, such as all campaign data for the past year.

Scheduling or automation, such as for nightly, weekly, or monthly reporting jobs that can run in the background and be retrieved when ready.

Avoiding timeouts and failures when data volume or processing time could exceed HTTP timeout limits.

Operational complexity:

Managing job IDs
Polling for status
Handling callbacks or retries

Delayed results, as report generation can take minutes or longer for large jobs.

Job expiry, where some platforms only retain completed reports available for a limited time, requiring you to download them promptly.

Error handling for job failures, partial data, or incomplete jobs.

To request a report and specify the information in it:

POST

Create async request for an account analytics report

To download the report when it is ready:

GET

Get the account analytics report created by the async call

Bulk

Pinterest provides entire datasets, such as all ad performance data for an account, in a single or batched file, sometimes in compressed formats.

Data warehousing and analytics, when you need to ingest large amounts of historical or raw data.

Data export for migration, backup, or compliance purposes.

Advanced, custom analysis on large datasets, for which multiple, smaller API calls would be impractical.

Very large files that may be hundreds of megabytes or more, requiring significant bandwidth, storage, and processing power.

Potential data staleness, as bulk data is often updated less frequently and may not reflect the most recent activity.

Parsing and processing time and overhead, such as the need for Extract, Transform, Load (ETL) pipelines.

Limited filtering and customization, where you get all the data, even if you only need a subset.

Security and compliance concerns, where handling large exports of sensitive data increases your responsibility for data protection.

Rate limits causing timeouts with large datasets, which could necessitate measures such as chunking requests by date.

To request an asynchronous bulk report:

POST

Get advertiser entities in bulk

To download the bulk report when it is ready:

GET

Download advertiser entities in bulk

    ...
    "500": "U.S.: Portland-Auburn",
    "501": "U.S.: New York",
    "502": "U.S.: Binghamton",
    "503": "U.S.: Macon",
    "504": "U.S.: Philadelphia",
    "505": "U.S.: Detroit",
    "506": "U.S.: Boston (Manchester)",
    "507": "U.S.: Savannah",
    ...
    "AR": "Argentina",
    "AU": "Australia",
    "AT": "Austria",
    "BE": "Belgium",
    "BR": "Brazil",
    "CA": "Canada",
    "CL": "Chile",
    ...

        ...
        "547": {
          "country": "US",
          "name": "Toledo"
        },
        "548": {
          "country": "US",
          "name": "West Palm Beach-Ft. Pierce"
        },
        "549": {
          "country": "US",
          "name": "Watertown"
        },
        ...
        "IT": {
          "country": "Italy",
          "regions": {
            "IT-23": {
              "country": "IT",
              "name": "Province of valle d'aosta"
        },
             "IT-36": {
               "country": "IT",
               "name": "Friuli Venezia Giulia"
        },
        ...
        "UST": {
          "country": "U.S. Territories",
          "regions": {
            "US-PR": {
              "country": "UST",
              "name": "Puerto Rico"
        },
        "US-VI": {
          "country": "UST",
          "name": "Virgin Islands"
          ...