> ## 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 Microsoft Ads data source in Adriel.

## Introduction

Microsoft Ads (Microsoft Advertising, formerly Bing Ads) is Microsoft's search and audience advertising platform, delivering ads across the Bing search engine, Yahoo, AOL, the Microsoft Audience Network, and partner properties. It is used by performance marketers to reach search and audience traffic outside the Google ecosystem, across search, shopping, dynamic search, audience, hotel, and Performance Max campaign types.

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 Microsoft Ads to Adriel](/data-sources/g-n/microsoft-ads/how-to-connect).

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, ad sets (ad groups), ads, and keywords. It refreshes twice daily, at **4:00 PM UTC** and **5:00 AM UTC**.

### Reports data

Reports include daily performance metrics for ad accounts, campaigns, ad sets, ads, and keywords.

**Real-time.** Report data is fetched from Microsoft Advertising on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled refreshes backfill late-arriving click and conversion data across several time windows.

**Refresh schedule.** Reports refresh on three overlapping schedules:

* **5:00 PM UTC daily** — syncs the last **9 days** for ad account, campaign, ad set, and ad
* **11:40 PM and 6:40 AM UTC daily** — syncs the last **3 days** for ad account, campaign, ad set, and ad
* **7:30 AM UTC on the 1st and 15th of each month** — syncs the last **30 days** for ad account, campaign, ad set, and ad

## Architecture levels

Customer → Ad account → Campaign → Ad set (ad group) → Ad / Keyword

## Date range limits

Some time-based breakdowns cap how far back a single report can reach. Data outside the cap may be truncated.

| Breakdown                  | Max range |
| -------------------------- | --------- |
| Daily                      | 93 days   |
| Week date                  | 93 days   |
| Weekly (Start: Mon or Sun) | 1 year    |

## 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 `Impressions` is the literal Microsoft Advertising (Bing Ads) reporting field. *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    | `Impressions` |
| Reach       | Unique users who saw the ad at least once.                      | Number    | `Reach`       |
| CPM         | Cost per thousand impressions.                                  | Currency  | `Cpm`         |

### Click performance

| Metric       | Description                                                   | Data type  | API Key  |
| ------------ | ------------------------------------------------------------- | ---------- | -------- |
| Clicks (all) | Total clicks, including link, social, and other interactions. | Number     | `Clicks` |
| Link clicks  | Clicks on the ad's link or call to action.                    | Number     | `Clicks` |
| CTR          | Click-through rate.                                           | Percentage | `Ctr`    |
| CPC          | Cost per click.                                               | Currency   | `Cpc`    |

### Cost & spend

<Note>
  When an ad account's currency differs from the Adriel workspace currency, costs are converted to the workspace currency using the current day's exchange rate.
</Note>

| Metric   | Description                                            | Data type | API Key           |
| -------- | ------------------------------------------------------ | --------- | ----------------- |
| Ad spend | Total amount spent on ads during the reporting period. | Currency  | `Spend`           |
| CPR      | Cost per result — spend divided by desired outcomes.   | Currency  | *Adriel-computed* |

### Conversion performance

| Metric           | Description                                                                                             | Data type  | API Key          |
| ---------------- | ------------------------------------------------------------------------------------------------------- | ---------- | ---------------- |
| Conversions      | Attributed actions matching the defined conversion events. Defaults to "Purchase" when no event is set. | Number     | `Conversions`    |
| Conversion value | Monetary value of attributed conversions.                                                               | Currency   | `Revenue`        |
| Revenue          | Monetary value of attributed conversions. Defaults to "Purchase" when no event is set.                  | Currency   | `Revenue`        |
| Result rate      | Conversion rate reported by the platform.                                                               | Percentage | `ConversionRate` |

### Per-conversion metrics

For each conversion goal tracked by the account's pixel, Adriel generates a set of derived metrics. The `[conversion_name]` placeholder is replaced with the goal name, for example `Microsoft Ads: Purchase`.

| Metric                                               | Description                                 | Data type  | API Key                                      |
| ---------------------------------------------------- | ------------------------------------------- | ---------- | -------------------------------------------- |
| Microsoft Ads: \[conversion\_name]                   | Number of conversions tracked for the goal. | Number     | *Per-goal conversion count*                  |
| Microsoft Ads: \[conversion\_name]: Conversion value | Value attributed to the goal.               | Currency   | *Per-goal conversion value*                  |
| Microsoft Ads: \[conversion\_name]: CPA              | Cost per action.                            | Currency   | *Adriel-computed (spend / conversions)*      |
| Microsoft Ads: \[conversion\_name]: CVR              | Conversion rate.                            | Percentage | *Adriel-computed (conversions / clicks)*     |
| Microsoft Ads: \[conversion\_name]: ROAS             | Return on ad spend.                         | Ratio      | *Adriel-computed (conversion value / spend)* |

### Video performance

| Metric                       | Description                                                     | Data type | API Key                   |
| ---------------------------- | --------------------------------------------------------------- | --------- | ------------------------- |
| Video impressions            | Number of times video creatives started displaying.             | Number    | `VideoImpressions`        |
| Views                        | Aggregated count of all qualified video views.                  | Number    | `VideoViews`              |
| Video played to 25% (Views)  | Plays reaching 25% of video length.                             | Number    | `Video25PercentComplete`  |
| Video played to 50% (Views)  | Plays reaching 50% of video length.                             | Number    | `Video50PercentComplete`  |
| Video played to 75% (Views)  | Plays reaching 75% of video length.                             | Number    | `Video75PercentComplete`  |
| Video played to 100% (Views) | Plays reaching 100% of video length.                            | Number    | `Video100PercentComplete` |
| 2s video plays               | Views where the video played for at least 2 seconds.            | Number    | `VideoViewsAt2Seconds`    |
| 6s video plays               | Views where the video played for at least 6 continuous seconds. | Number    | `VideoViewsAt6Seconds`    |

### Budget & schedule

| Metric       | Description                                                      | Data type | API Key                                                        |
| ------------ | ---------------------------------------------------------------- | --------- | -------------------------------------------------------------- |
| Budget       | Configured budget (daily or lifetime) on the campaign or ad set. | Currency  | `DailyBudget`, `CpcBid.Amount`                                 |
| Daily budget | Daily budget set on the campaign or ad set.                      | Currency  | `DailyBudget`, `CpcBid.Amount`                                 |
| Bid cap      | Bid cap set on the ad set or campaign.                           | Currency  | `CpcBid.Amount`, `Bid.Amount`                                  |
| Bid strategy | Bid strategy set on the ad set or campaign.                      | Text      | `BiddingScheme.Type`, `BiddingScheme.InheritedBidStrategyType` |
| Starts       | Campaign or ad set start date.                                   | Date      | `StartDate`                                                    |
| Ends         | Campaign or ad set end date.                                     | Date      | `EndDate`                                                      |

### Campaign structure metadata

| Metric          | Description                            | Data type | API Key                                             |
| --------------- | -------------------------------------- | --------- | --------------------------------------------------- |
| Ad account name | Name of the ad account.                | Text      | `Name`, `a:Name`                                    |
| Campaign name   | Campaign name.                         | Text      | `Name`                                              |
| Ad set name     | Ad set (ad group) name.                | Text      | `Name`                                              |
| Ad name         | Ad name.                               | Text      | `TitlePart1`, `TitlePart2`, `TitlePart3`, `Type`    |
| Keyword name    | Keyword text (Search campaigns only).  | Text      | `Text`                                              |
| Objective       | Campaign objective or type.            | Text      | `CampaignType`                                      |
| Status          | Campaign, ad set, or ad status.        | Text      | `Status`                                            |
| Channel         | Channel where the ad is published.     | Text      | *Constant rollup label*                             |
| Creative type   | Ad type.                               | Text      | `Type`                                              |
| Creative URL    | Creative image or video thumbnail URL. | URL       | `Images.ImageUrl`, `Videos.ThumbnailImage.ImageUrl` |

### UTM tracking

<Note>
  UTM values are parsed by Adriel, not returned by Microsoft. Adriel reads the UTM query parameters from each ad's landing URL.
</Note>

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

## Breakdowns

### Standard hierarchy

| Breakdown     | Description                               | API Key                                          |
| ------------- | ----------------------------------------- | ------------------------------------------------ |
| Ad account    | Group by ad account (based on ID).        | `Name`, `a:Name`                                 |
| Campaign      | Group by campaign (based on ID).          | `Name`                                           |
| Ad set        | Group by ad set / ad group (based on ID). | `Name`                                           |
| Ad            | Group by ad (based on ID).                | `TitlePart1`, `TitlePart2`, `TitlePart3`, `Type` |
| Campaign name | Group by campaign name.                   | `Name`                                           |
| Ad set name   | Group by ad set name.                     | `Name`                                           |
| Ad name       | Group by ad name.                         | `TitlePart1`, `TitlePart2`, `TitlePart3`, `Type` |

### Search

<Note>
  These breakdowns apply only to Search campaigns; they return no data for other campaign types.
</Note>

| Breakdown        | Description                                      | API Key                    |
| ---------------- | ------------------------------------------------ | -------------------------- |
| Keyword          | Group by keyword (based on keyword ID).          | `Text`                     |
| Keyword text     | Group by keyword text.                           | `Text`                     |
| Search term view | Group by the search query that triggered the ad. | *Microsoft reporting view* |

### Demographics & geography

| Breakdown     | Description                                             | API Key                        |
| ------------- | ------------------------------------------------------- | ------------------------------ |
| Age           | Group by audience age range.                            | `AgeGroup`                     |
| Gender        | Group by audience gender.                               | `Gender`                       |
| Country       | Group by impression location (two-letter country code). | *Derived from location fields* |
| Location      | Split reports by impression location (city or region).  | `Country`, `Region`, `City`    |
| Device target | Group by device type (mobile, desktop, or tablet).      | `DeviceType`                   |

### Campaign attributes

| Breakdown | Description                                         | API Key        |
| --------- | --------------------------------------------------- | -------------- |
| Objective | Group campaigns by their objective (campaign type). | `CampaignType` |
| Status    | Group by campaign, ad set, or ad status.            | `Status`       |

### Time grouping

<Note>
  Microsoft returns daily records; Adriel aggregates them into these views for reporting.
</Note>

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

### Creative analysis

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

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

### Overview

<Note>
  These groupings are provided by Adriel rather than returned by the Microsoft reporting API.
</Note>

| Breakdown   | Description                                                 |
| ----------- | ----------------------------------------------------------- |
| Channel     | Constant grouping label, used for cross-connector rollup.   |
| Platform    | Group results by the platform where the ads were broadcast. |
| No Grouping | Do not break down; return one aggregated row.               |

## Limitations

* **Keyword data is Search-only** — keyword and keyword-text breakdowns and the keyword-name metric return data only for Search campaigns.
* **Date-range caps on time breakdowns** — daily and week-date breakdowns are limited to 93 days; weekly breakdowns are limited to 1 year. Data outside these ranges may be truncated.
* **Customer and account header pairing** — every request requires both the Microsoft customer ID and the account ID. A mismatched pairing returns a permission error rather than empty data, so both must be selected consistently during setup.
* **Currency conversion** — when an ad account's currency differs from the workspace currency, costs are converted using the current day's exchange rate, so historical currency figures may shift slightly.

## API references

* [Microsoft Advertising API overview](https://learn.microsoft.com/en-us/advertising/guides/)
* [Reporting Service reference (v13)](https://learn.microsoft.com/en-us/advertising/reporting-service/reporting-service-reference)
* [Campaign Management Service reference (v13)](https://learn.microsoft.com/en-us/advertising/campaign-management-service/campaign-management-service-reference)
* [Customer Management Service reference (v13)](https://learn.microsoft.com/en-us/advertising/customer-management-service/customer-management-service-reference)

## See also

* [How to connect Microsoft Ads to Adriel](/data-sources/g-n/microsoft-ads/how-to-connect) (paired how-to)
* [Google Ads data reference](/data-sources/g-n/google-ads/data-reference) — for comparison across search platforms
* [Yahoo Ads data reference](/data-sources/o-z/yahoo-ads/data-reference) — another search and audience network