Data reference

Introduction

Pinterest Ads is the paid advertising side of Pinterest, the visual discovery platform. It is used by brand and performance marketers to deliver promoted pins, shopping ads, and video ads to Pinterest users who are actively searching for inspiration in categories such as fashion, home, food, and travel. Pinterest Ads supports CPC, CPM, and CPV payment models across campaign objectives ranging from awareness through conversions and catalog sales. The connector imports the resulting structure and performance data through the Pinterest Ads API v5. As a marketing connector, metrics, breakdowns, and currencies are standardized so widgets can aggregate across sources without additional configuration. To connect this data source, see How to connect Pinterest Ads to Adriel.

Data refresh strategy

Architecture data

Architecture covers ad accounts, campaigns, ad sets, and ads. It refreshes twice daily at 4:00 PM UTC and 5:00 AM UTC. On data source creation, the cache fills with 365 days of historical data for the ad account, campaign, ad set, and ad levels.

Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, and ads. Cache-only. Report data comes from cached daily performance snapshots. Dashboard queries always read from the last snapshot, never live from Pinterest, so very recent changes inside Pinterest Ads Manager appear only after the next scheduled sync. Uniqueness caveat. Metrics based on uniqueness, such as reach, can be overvalued when viewed over date ranges longer than one day, because uniqueness is computed per snapshot rather than across the full range. Refresh schedule. Reports refresh on this cadence:

6:00 PM UTC — syncs the last 7 days for these breakdowns (each per ad account): search term view, OS, gender, location, platform placement, country, audience, and age.
5:00 PM UTC — syncs the last 9 days for the ad account, campaign, ad set, and ad levels.
9:00 PM UTC and 6:00 AM UTC — sync the last 3 days for the ad account, campaign, ad set, and ad levels.
3:00 AM UTC and 8:00 AM UTC — sync the last 1 day for the ad account, campaign, ad set, and ad levels.
3:00 PM UTC on day 3 of the month — syncs the last 35 days for the ad account, campaign, ad set, and ad levels.

Data is reliable within the cache sync period. Data outside this range may be incomplete or inaccurate.

Architecture levels

Ad account → Campaign → Ad set (ad group) → Ad (promoted pin)

Date range limits

Breakdown	Max range
Daily	93 days
Weekly	1 year
Monthly	2 years

Metrics

How to read the columns Data type uses this vocabulary: Number, Currency, Percentage, Ratio, Duration, Date, Text, URL, Array, Boolean. API Key in code style like TOTAL_IMPRESSION is the literal Pinterest API field name. Italic text describes how a value is produced when it does not map cleanly to a single API field.

Reach & impressions

Metric	Description	Data type	API Key
Impressions	Total times ads were displayed, regardless of user interaction.	Number	`TOTAL_IMPRESSION`
Reach	Unique users who saw the ad at least once.	Number	`TOTAL_IMPRESSION_USER`
CPM	Cost per thousand impressions.	Currency	Adriel-computed (spend / impressions × 1000)

Click performance

Metric	Description	Data type	API Key
Link clicks	Number of times users clicked the ad’s link.	Number	`TOTAL_CLICKTHROUGH`
Clicks (all)	Total clicks, including link, social, carousel, and other interactions.	Number	`TOTAL_CLICKTHROUGH`
Outbound clicks	Clicks that drove traffic to the destination URL.	Number	`OUTBOUND_CLICK_1`
CTR	Click-through rate.	Percentage	Adriel-computed (clicks / impressions)
CPC	Cost per click.	Currency	Adriel-computed (spend / clicks)

Cost & spend

Currency values are reported in each ad account’s configured Pinterest currency. Several Pinterest value fields are returned in micro-dollars (millionths of a unit); Adriel converts them to the account currency, and to the workspace currency using the day’s exchange rate when the two differ.

Metric	Description	Data type	API Key
Ad spend	Total amount spent on ads during the reporting period.	Currency	`SPEND_IN_DOLLAR`

Engagement

Metric	Description	Data type	API Key
Engagement	Any user interaction with the ad: clicks, reactions, shares, and saves.	Number	Aggregated from Pinterest engagement actions
Saves	Pin saves attributed to the campaign.	Number	`REPIN_1`
Post comments	Comments on the ad post.	Number	Derived from Pinterest engagement actions
Post reactions	Reactions to the ad post.	Number	Derived from Pinterest engagement actions
Post shares	Shares of the ad post.	Number	Derived from Pinterest engagement actions
Post saves	Saves of the ad post.	Number	Derived from Pinterest engagement actions
Post engagement	Total engagement on the ad post.	Number	Derived from Pinterest engagement actions

Video performance

Metric	Description	Data type	API Key
Video impressions	Number of times video creatives started displaying.	Number	Derived from video reporting
Video play	Any play of the video, regardless of duration.	Number	Derived from video reporting
Video views (3s)	Views of at least three continuous seconds.	Number	`VIDEO_3SEC_VIEWS_2`
Video played to 25%	Plays reaching 25% of video length.	Number	`TOTAL_VIDEO_P25_COMBINED`
Video played to 50%	Plays reaching 50% of video length.	Number	`TOTAL_VIDEO_P50_COMBINED`
Video played to 75%	Plays reaching 75% of video length.	Number	`TOTAL_VIDEO_P75_COMBINED`
Video played to 100%	Plays reaching 100% of video length.	Number	`TOTAL_VIDEO_P100_COMPLETE`
Views	Aggregated count of all qualified video views.	Number	`TOTAL_VIDEO_P100_COMPLETE`
2s video plays	Views where the video played for at least two seconds.	Number	Derived from video reporting
6s video plays	Six-second continuous video views.	Number	Derived from video reporting
15s video plays	Views lasting at least fifteen continuous seconds.	Number	Derived from video reporting
30s video plays	Views lasting 30 seconds, or the entire video if shorter.	Number	Derived from video reporting
ThruPlays	Video viewed to at least 97%, or 15 seconds, whichever comes first.	Number	Derived from video reporting

Conversion performance

Metric	Description	Data type	API Key
Conversions	Attributed actions matching the defined conversion events. When no specific conversion event is set, this defaults to “Purchase”.	Number	`TOTAL_CONVERSIONS`
Conversion value	Monetary value of attributed conversions.	Currency	`TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Revenue	Monetary value of attributed conversions. When no specific conversion event is set, this defaults to “Purchase”.	Currency	`TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
All conversions	Count of every conversion action recorded for the element.	Number	Derived from conversion reporting
ROAS	Return on ad spend.	Ratio	Adriel-computed (conversion value / spend)
CPA	Cost per acquisition.	Currency	Adriel-computed (spend / conversions)
CPR	Cost per result.	Currency	Adriel-computed (spend / results)
Conversion rate	Conversions divided by clicks.	Percentage	Adriel-computed

Attributed conversion values

These value metrics are returned in micro-dollars (millionths of a unit) and split by attribution type (click, view, engagement, web) and event (checkout, signup, custom). Adriel converts them to the account currency.

Metric	Description	Data type	API Key
Checkout value	Total value of attributed checkout conversions.	Currency	`TOTAL_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Signup value	Total value of attributed signup conversions.	Currency	`TOTAL_SIGNUP_VALUE_IN_MICRO_DOLLAR`
Custom conversion value	Total value of attributed custom conversions.	Currency	`TOTAL_CUSTOM_VALUE_IN_MICRO_DOLLAR`
Click-attributed checkout value	Checkout value attributed to clicks.	Currency	`TOTAL_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Click-attributed signup value	Signup value attributed to clicks.	Currency	`TOTAL_CLICK_SIGNUP_VALUE_IN_MICRO_DOLLAR`
View-attributed checkout value	Checkout value attributed to views.	Currency	`TOTAL_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
View-attributed signup value	Signup value attributed to views.	Currency	`TOTAL_VIEW_SIGNUP_VALUE_IN_MICRO_DOLLAR`
Engagement-attributed checkout value	Checkout value attributed to engagements.	Currency	`TOTAL_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Engagement-attributed signup value	Signup value attributed to engagements.	Currency	`TOTAL_ENGAGEMENT_SIGNUP_VALUE_IN_MICRO_DOLLAR`
Web checkout value	Total value of attributed web checkout conversions.	Currency	`TOTAL_WEB_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Web click-attributed checkout value	Web checkout value attributed to clicks.	Currency	`TOTAL_WEB_CLICK_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Web view-attributed checkout value	Web checkout value attributed to views.	Currency	`TOTAL_WEB_VIEW_CHECKOUT_VALUE_IN_MICRO_DOLLAR`
Web engagement-attributed checkout value	Web checkout value attributed to engagements.	Currency	`TOTAL_WEB_ENGAGEMENT_CHECKOUT_VALUE_IN_MICRO_DOLLAR`

Dynamic conversion metrics

Custom conversion events tracked in the ad account are imported automatically. For each event, Adriel derives ROAS, CPA, and conversion-rate metrics when the underlying data is available.

Budget & schedule

Metric	Description	Data type	API Key
Budget	Budget set on the campaign or ad set; can be daily or lifetime.	Currency	`lifetime_spend_cap`
Daily budget	Daily budget allocation.	Currency	`daily_spend_cap`
Lifetime budget	Total budget allocated for the campaign’s entire lifetime.	Currency	Derived from budget configuration
Bid cap	Bid cap on the ad set or campaign.	Currency	Derived from bid configuration
Bid strategy	Bid strategy on the ad set or campaign.	Text	Derived from bid configuration
Starts	Campaign or ad start time.	Date	`start_time`
Ends	Campaign or ad end time.	Date	`end_time`
Number of days per row	Number of days covered by each report row.	Number	Adriel-computed
Remaining days	Days remaining until the end date.	Number	Adriel-computed

UTM tracking

UTM values are parsed by Adriel, not returned by Pinterest. Adriel reads the UTM query parameters from each ad’s configuration or landing URL and exposes them as both metrics (for rollup) and breakdowns (for grouping).

Metric	Description	API Key
UTM Source	Parsed `utm_source` parameter.	Adriel-parsed from landing URL
UTM Medium	Parsed `utm_medium` parameter.	Adriel-parsed
UTM Campaign	Parsed `utm_campaign` parameter.	Adriel-parsed
UTM Content	Parsed `utm_content` parameter.	Adriel-parsed
UTM Term	Parsed `utm_term` parameter.	Adriel-parsed

Campaign structure metadata

Metric	Description	Data type	API Key
Ad account name	Name of the ad account.	Text	`owner.username`
Campaign name	Campaign name.	Text	`name`
Ad set name	Ad set name.	Text	`name`
Ad name	Ad name.	Text	`name`
Keyword name	Keyword name for search campaigns.	Text	Derived from search campaign data
Channel	Channel where the ad is published.	Text	Adriel-standardized
Objective	Campaign objective.	Text	`objective_type`
Status	Campaign, ad set, or ad status.	Text	`status`
Creative type	Format of the ad.	Text	Resolved from creative metadata
Creative URL	Ad creative URL reference.	URL	`pin.media.images`

Breakdowns

Standard hierarchy

Breakdown	Description	API Key
Ad account	Group by ad account.	`owner.username`
Campaign	Group by campaign.	`campaign_id`
Ad set	Group by ad set (ad group).	`ad_group_id`
Ad	Group by individual promoted pin.	`ad_id`

Demographics & geography

Demographic and geographic breakdowns are reported per ad account only and cannot be combined with campaign, ad set, or ad granularity in the same query.

Breakdown	Description	API Key
Age	Audience age bucket.	`age_bucket`
Gender	Audience gender.	`gender`
Country	Country of the impression.	`country`
Location	Geographic location.	`location`
Audience	Audience segment.	`audience`

Placement & device

Placement and device breakdowns are reported per ad account only.

Breakdown	Description	API Key
Device / OS	Operating system or device class.	`os`
Platform placement	Placement surface where the ad was served.	`platform_placement`
Platform	Platform where the ads were broadcast.	`platform`

Search

The search-term breakdown is reported per ad account only.

Breakdown	Description	API Key
Search term	Search term that triggered the impression.	`search_term_view`

Overview & status

Breakdown	Description	API Key
Channel	Constant grouping label used for cross-connector rollup.	`channel`
Objective	Group campaigns by their objective.	`objective_type`
Status	Group by campaign, ad set, or ad status.	`status`

Time & date grouping

Pinterest returns daily records; Adriel groups them into these views for reporting. All time-grouping breakdowns are Adriel-side aggregations of the same underlying daily data.

Breakdown	Description
Auto Time Breakdown	Automatically picks the best granularity for the date range.
Daily	Split reports by day (for example, 2025-06-08).
Weekly (Start: Mon)	Split reports by week, starting Monday.
Weekly (Start: Sun)	Split reports by week, starting Sunday.
Week Date Breakdown	Group results by the day of the week on which the impression occurred.
Week Number Breakdown (W#)	Split by week number in the year.
Monthly	Split reports by calendar month.
Quarterly	Split reports by calendar quarter (for example, Q2 2025).
Yearly	Split reports by calendar year.

Creative analysis

Adriel post-processes ad creatives to generate these breakdowns.

Breakdown	Description
Creative image	Groups reports by image, clustering identical or visually similar creatives.
Ad copy	Groups ads that share the same ad copy.
Color Clustering	Groups creative images by dominant visual color.
Emoji Analysis	Groups ads by the emojis present in the ad copy.

UTM tracking

Pinterest does not return UTM values; Adriel parses them from each ad’s configuration or landing URL and exposes them as breakdowns for grouping.

Breakdown	Description
UTM Source	Group by parsed `utm_source`.
UTM Medium	Group by parsed `utm_medium`.
UTM Campaign	Group by parsed `utm_campaign`.
UTM Content	Group by parsed `utm_content`.
UTM Term	Group by parsed `utm_term`.

No grouping

Returns one aggregated row without breaking the data down.

Breakdown	Description
No Grouping	Do not break down; return a single aggregated row.

Limitations

Ad-account-only demographic breakdowns — demographic, geographic, placement, and search-term breakdowns (age, gender, country, location, audience, OS, platform placement, search term) are reported per ad account only. They cannot be combined with campaign, ad set, or ad granularity in the same query.
Cache-only reads — dashboards never query Pinterest live for reports; all metric values come from the most recent cache snapshot, so very recent changes appear only after the next scheduled sync.
Uniqueness overcounting — uniqueness-based metrics such as reach are computed per snapshot and can be overvalued over date ranges longer than one day.
No deleted-data retention — this connector does not provide deleted elements. Data is not available after an element is deleted on the platform.
Automatic query chunking — report queries are split into chunks of at most 186 days per request and merged before parsing; this is automatic and requires no user action.
Currency conversion — when the ad account currency differs from the workspace currency, values are converted automatically using the current day’s exchange rate.

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Reach & impressions

Click performance

Cost & spend

Engagement

Video performance

Conversion performance

Attributed conversion values

Dynamic conversion metrics

Budget & schedule

UTM tracking

Campaign structure metadata

Breakdowns

Standard hierarchy

Demographics & geography

Placement & device

Search

Overview & status

Time & date grouping

Creative analysis

UTM tracking

No grouping

Limitations

API references

See also

​Introduction

​Data refresh strategy

​Architecture data

​Reports data

​Architecture levels

​Date range limits

​Metrics

​Reach & impressions

​Click performance

​Cost & spend

​Engagement

​Video performance

​Conversion performance

​Attributed conversion values

​Dynamic conversion metrics

​Budget & schedule

​UTM tracking

​Campaign structure metadata

​Breakdowns

​Standard hierarchy

​Demographics & geography

​Placement & device

​Search

​Overview & status

​Time & date grouping

​Creative analysis

​UTM tracking

​No grouping

​Limitations

​API references

​See also

Introduction

Data refresh strategy

Architecture data

Reports data

Architecture levels

Date range limits

Metrics

Reach & impressions

Click performance

Cost & spend

Engagement

Video performance

Conversion performance

Attributed conversion values

Dynamic conversion metrics

Budget & schedule

UTM tracking

Campaign structure metadata

Breakdowns

Standard hierarchy

Demographics & geography

Placement & device

Search

Overview & status

Time & date grouping

Creative analysis

UTM tracking

No grouping

Limitations

API references

See also