> ## Documentation Index
> Fetch the complete documentation index at: https://docs.adriel.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Data reference

> Metrics, breakdowns, refresh cadence, and limits for the Pinterest Ads data source in Adriel.

## 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-sources/o-z/pinterest-ads/how-to-connect).

## 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

<Note>
  **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.
</Note>

### 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

<Note>
  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.
</Note>

| 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

<Note>
  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.
</Note>

| 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

<Note>
  **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).
</Note>

| 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

<Note>
  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.
</Note>

| 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

<Note>
  Placement and device breakdowns are reported per ad account only.
</Note>

| 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

<Note>
  The search-term breakdown is reported per ad account only.
</Note>

| 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

<Note>
  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.
</Note>

| 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

<Note>
  Adriel post-processes ad creatives to generate these breakdowns.
</Note>

| 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

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

| 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

<Note>
  Returns one aggregated row without breaking the data down.
</Note>

| 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.

## API references

* [Pinterest Ads API v5 — Reporting](https://developers.pinterest.com/docs/api/v5/reports-create/)
* [Pinterest Ads API v5 — Analytics](https://developers.pinterest.com/docs/api/v5/ad_accounts-analytics/)
* [Pinterest Ads API v5 — Overview](https://developers.pinterest.com/docs/api/v5/)

## See also

* [How to connect Pinterest Ads to Adriel](/data-sources/o-z/pinterest-ads/how-to-connect) (paired how-to)
* [Pinterest Organic data reference](/data-sources/o-z/pinterest-organic/data-reference) — for organic pin analytics