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

## Introduction

LinkedIn Ads is LinkedIn's B2B-focused paid advertising platform, used to run Sponsored Content, Sponsored Messaging, Text Ads, Dynamic Ads, and Lead Gen Forms across the LinkedIn feed and inbox. It supports CPC, CPM, and CPS payment models across awareness, consideration, and conversion objectives, with audience targeting built on professional attributes such as company, industry, job function, job title, and seniority. The connector imports campaign structure, performance metrics, and conversion data through LinkedIn's Marketing Developer Platform.

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

## Data refresh strategy

### Architecture data

Architecture covers ad accounts, campaigns, and ads. 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, and ads.

**Real-time.** Report data is fetched from LinkedIn on demand when a dashboard loads, so the latest values are always visible. On top of that, scheduled cache refreshes keep historical data consistent across multiple 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

Ad account → Campaign → (Ad set = duplicate of campaign) → Ad

<Note>
  **LinkedIn has no native ad set entity**
  Both the campaign and ad set levels query the same LinkedIn endpoint, so the same campaigns appear at both hierarchy levels. Ad-set-level queries returning identical data to campaign-level queries is expected behavior, not a bug.
</Note>

## 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 `impressions` is the literal LinkedIn API field name. *Italic text* describes how a value is produced when it doesn't map cleanly to a single API field.
</Note>

### Reach & impressions

| Metric      | Description                                                | Data type | API Key                  |
| ----------- | ---------------------------------------------------------- | --------- | ------------------------ |
| Impressions | Total times the ads were shown, regardless of interaction. | Number    | `impressions`            |
| Reach       | Unique members who saw the ad at least once.               | Number    | `approximateMemberReach` |

### 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.                                      | Number     | `clicks`                                 |
| Landing page clicks | Clicks specifically to landing pages.                         | Number     | *LinkedIn-specific*                      |
| CTR                 | Click-through rate.                                           | Percentage | *Adriel-computed (clicks ÷ impressions)* |

### Cost & spend

<Note>
  Currency values are reported in each ad account's configured LinkedIn currency. When the ad account currency differs from the workspace currency, values are converted using the current day's exchange rate.
</Note>

| Metric   | Description                    | Data type | API Key                                        |
| -------- | ------------------------------ | --------- | ---------------------------------------------- |
| Ad spend | Total amount spent.            | Currency  | `costInLocalCurrency`                          |
| CPM      | Cost per thousand impressions. | Currency  | *Adriel-computed (spend ÷ impressions × 1000)* |
| CPC      | Cost per click.                | Currency  | *Adriel-computed (spend ÷ clicks)*             |
| CPR      | Cost per result.               | Currency  | *Adriel-computed (spend ÷ results)*            |

### Engagement

| Metric              | Description                                                              | Data type | API Key             |
| ------------------- | ------------------------------------------------------------------------ | --------- | ------------------- |
| Engagement          | Any user interaction with the ad, such as clicks, reactions, and shares. | Number    | `totalEngagements`  |
| Total engagements   | LinkedIn-specific total engagements.                                     | Number    | `totalEngagements`  |
| Reactions           | Total reactions on the ad.                                               | Number    | *LinkedIn-specific* |
| Likes               | Like reactions.                                                          | Number    | *LinkedIn-specific* |
| Comments            | Comments on the ad.                                                      | Number    | *LinkedIn-specific* |
| Shares              | Shares of the ad.                                                        | Number    | *LinkedIn-specific* |
| Follows             | Follower acquisitions attributed to the ads.                             | Number    | *LinkedIn-specific* |
| Company page clicks | Clicks through to the company page.                                      | Number    | *LinkedIn-specific* |
| Opens               | Sponsored Messaging opens.                                               | Number    | *LinkedIn-specific* |
| Sends               | Sponsored Messaging sends.                                               | Number    | *LinkedIn-specific* |

### Lead generation

| Metric            | Description                                                   | Data type | API Key             |
| ----------------- | ------------------------------------------------------------- | --------- | ------------------- |
| LinkedIn leads    | Total leads attributed to LinkedIn.                           | Number    | *LinkedIn-specific* |
| One-click leads   | Leads generated via Lead Gen Forms with one-click submission. | Number    | *LinkedIn-specific* |
| Lead forms opened | Times a Lead Gen Form was opened.                             | Number    | *LinkedIn-specific* |

### Video performance

| Metric                       | Description                                                         | Data type | API Key             |
| ---------------------------- | ------------------------------------------------------------------- | --------- | ------------------- |
| Video impressions            | Times video creatives started displaying.                           | Number    | `videoViews`        |
| Views                        | Aggregated count of all qualified video views.                      | Number    | *LinkedIn-specific* |
| Video play                   | Any play of the video, regardless of duration.                      | Number    | *LinkedIn-specific* |
| 2s video plays               | Plays lasting at least two continuous seconds.                      | Number    | *LinkedIn-specific* |
| 3s video plays               | Plays lasting at least three continuous seconds.                    | Number    | *LinkedIn-specific* |
| 6s video plays               | Plays lasting at least six continuous seconds.                      | Number    | *LinkedIn-specific* |
| 15s video plays              | Plays lasting at least fifteen continuous seconds.                  | Number    | *LinkedIn-specific* |
| 30s video plays              | Plays lasting 30 seconds, or the entire video if shorter.           | Number    | *LinkedIn-specific* |
| Video played to 25% (Views)  | Plays reaching 25% of video length.                                 | Number    | *LinkedIn-specific* |
| Video played to 50% (Views)  | Plays reaching 50% of video length.                                 | Number    | *LinkedIn-specific* |
| Video played to 75% (Views)  | Plays reaching 75% of video length.                                 | Number    | *LinkedIn-specific* |
| Video played to 100% (Views) | Plays reaching 100% of video length.                                | Number    | *LinkedIn-specific* |
| ThruPlays                    | Video viewed to at least 97%, or 15 seconds, whichever comes first. | Number    | *LinkedIn-specific* |

### Conversion performance

| Metric           | Description                                                          | Data type | API Key                          |
| ---------------- | -------------------------------------------------------------------- | --------- | -------------------------------- |
| Conversions      | Attributed actions matching the defined conversion events.           | Number    | `externalWebsiteConversions`     |
| Conversion value | Monetary value of attributed conversions.                            | Currency  | `conversionValueInLocalCurrency` |
| Revenue          | Monetary value of attributed conversions (same as Conversion value). | Currency  | `conversionValueInLocalCurrency` |

### Custom conversion events

LinkedIn conversion data is fetched in a separate query and joined to the main analytics response. Named conversion events are resolved by calling LinkedIn's conversions endpoint to build an ID-to-name map. For each conversion event configured in the connected LinkedIn ad account, the following metrics are generated:

| Pattern                                        | Description                    | Data type  | API Key                                   |
| ---------------------------------------------- | ------------------------------ | ---------- | ----------------------------------------- |
| `LinkedIn Ads: [event_name]`                   | Count of the conversion event. | Number     | *Resolved via conversions API*            |
| `LinkedIn Ads: [event_name]: Conversion value` | Monetary value of the event.   | Currency   | *Resolved via conversions API*            |
| `LinkedIn Ads: [event_name]: CPA`              | Cost per action.               | Currency   | *Adriel-computed (spend ÷ count)*         |
| `LinkedIn Ads: [event_name]: ROAS`             | Return on ad spend.            | Ratio      | *Adriel-computed (value ÷ spend)*         |
| `LinkedIn Ads: [event_name]: CVR`              | Conversion rate.               | Percentage | *Adriel-computed (count ÷ clicks × 100%)* |

<Note>
  **Conversion stub rows for missing metric matches**
  When a conversion row exists for a date and pivot combination that has no matching metric row, for example an entity with conversions but zero impressions, a stub row with empty metrics is synthesized so the conversion data is preserved.
</Note>

<Note>
  **Raw LinkedIn pass-through metrics**
  Several metrics are also exposed in a raw `LinkedIn Ads: [metric]` form directly from the LinkedIn API, for example `LinkedIn Ads: Impressions`, `LinkedIn Ads: Landing Page Clicks`, `LinkedIn Ads: Total Engagements`, and `LinkedIn Ads: Cost In Local Currency`. These mirror the standardized metrics above.
</Note>

### Budget & schedule

| Metric          | Description                                                | Data type | API Key                                |
| --------------- | ---------------------------------------------------------- | --------- | -------------------------------------- |
| Budget          | Total budget on the campaign or ad set.                    | Currency  | `totalBudget.amount`                   |
| Daily budget    | Daily budget on the campaign or ad set.                    | Currency  | `dailyBudget.amount`                   |
| Lifetime budget | Total budget allocated for the campaign's entire lifetime. | Currency  | *Resolved from LinkedIn budget fields* |
| Bid strategy    | Cost-type bid strategy.                                    | Text      | `costType`                             |
| Starts          | Schedule start date.                                       | Date      | `runSchedule.start`                    |
| Ends            | Schedule end date; omitted when it is today.               | Date      | `runSchedule.end`                      |

### UTM tracking

<Note>
  **UTM values are parsed by Adriel, not returned by LinkedIn.** Adriel reads the UTM query parameters from each ad's configuration and landing URL and exposes them for rollup and grouping.
</Note>

| Metric       | Description                      | API Key                                       |
| ------------ | -------------------------------- | --------------------------------------------- |
| UTM Source   | Parsed `utm_source` parameter.   | *Adriel-parsed from ad config or 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      | `name`                                        |
| Campaign name   | Campaign name.                                     | Text      | `name`                                        |
| Ad set name     | Ad set name; uses the same field as campaign.      | Text      | `name`                                        |
| Ad name         | Ad name.                                           | Text      | `name`                                        |
| Keyword name    | Keyword name; available only for search campaigns. | Text      | *LinkedIn-specific*                           |
| Channel         | Channel where the ad is published.                 | Text      | *Constant value ("linkedin")*                 |
| Status          | Campaign, ad set, or ad status.                    | Text      | `status`, `servingStatuses`, `intendedStatus` |
| Objective       | Campaign objective.                                | Text      | `objectiveType`                               |
| Creative URL    | Preview URL for the creative.                      | URL       | `creativeParams.previewUrl`                   |

## Breakdowns

LinkedIn supports several segmentation breakdowns, subject to the limits described in [Limitations](#limitations): a maximum of two breakdowns per query, and no detail breakdowns at ad level.

### Standard hierarchy

| Breakdown  | Description                              | API Key |
| ---------- | ---------------------------------------- | ------- |
| Ad account | Group by ad account.                     | `name`  |
| Campaign   | Group by campaign.                       | `name`  |
| Ad set     | Group by ad set; same field as campaign. | `name`  |
| Ad         | Group by ad.                             | `name`  |

### Audience & company

| Breakdown    | Description                       | API Key               |
| ------------ | --------------------------------- | --------------------- |
| Industry     | Group by member industry.         | `MEMBER_INDUSTRY`     |
| Company      | Group by member company.          | `MEMBER_COMPANY`      |
| Company size | Group by member company size.     | `MEMBER_COMPANY_SIZE` |
| Seniority    | Group by member career seniority. | `MEMBER_SENIORITY`    |
| Job function | Group by member job function.     | `MEMBER_JOB_FUNCTION` |
| Job title    | Group by member job title.        | `MEMBER_JOB_TITLE`    |

### Geography

| Breakdown | Description                                                        | API Key             |
| --------- | ------------------------------------------------------------------ | ------------------- |
| Country   | Group by impression location (country).                            | `MEMBER_COUNTRY_V2` |
| US State  | Group by US state; non-US impressions fall back to an "OTHER" row. | `MEMBER_REGION_V2`  |
| Location  | Group by impression location (region).                             | `MEMBER_REGION_V2`  |

### Device

| Breakdown     | Description                                             | API Key                  |
| ------------- | ------------------------------------------------------- | ------------------------ |
| Device target | Group by the device on which the impression was served. | `IMPRESSION_DEVICE_TYPE` |

### Campaign attributes

| Breakdown | Description                              | API Key                                       |
| --------- | ---------------------------------------- | --------------------------------------------- |
| Objective | Group by campaign objective.             | `objectiveType`                               |
| Status    | Group by campaign, ad set, or ad status. | `status`, `servingStatuses`, `intendedStatus` |

### Time & date grouping

<Note>
  LinkedIn returns daily records; Adriel groups them into these views for reporting, so 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.                                        |
| Weekly (Start: Mon)        | Split reports by week, starting Monday.                      |
| Weekly (Start: Sun)        | Split reports by week, starting Sunday.                      |
| Week date breakdown        | Group by the day of the week 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.                           |
| Yearly                     | Split reports by calendar year.                              |

### Creative analysis

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

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

### UTM tracking

<Note>
  LinkedIn doesn't return UTM values; Adriel parses them from each ad's configuration and 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`.     |

### Overview & status

<Note>
  These grouping options are Adriel-side conveniences that don't correspond to a LinkedIn segmentation pivot.
</Note>

| Breakdown   | Description                                                                                            |
| ----------- | ------------------------------------------------------------------------------------------------------ |
| Channel     | Constant grouping label — for LinkedIn Ads this is always "linkedin". Used for cross-connector rollup. |
| No Grouping | Do not break down; return one aggregated row.                                                          |
| Platform    | Group results by the platform where the ads were broadcast.                                            |

## Limitations

* **Maximum 2 breakdowns per query.** Adriel's LinkedIn connector caps each query at two breakdowns at once; adding a third returns a "too much breakdowns" error. This is an Adriel connector limit, not a LinkedIn platform restriction.
* **Detail breakdowns not supported at ad level.** Detail breakdowns must be queried at the ad account, campaign, or ad set level; querying one at ad level returns an error.
* **Detail breakdown with conversion metrics.** Conversion data is not returned for queries that include a detail breakdown.
* **20-item architecture filter cap.** When more than 20 campaigns, groups, or creatives are selected in the data source filter, the filter is dropped and account-level (unfiltered) data is returned. Use a breakdown for finer granularity past 20 items.
* **Ad set duplicates campaign.** LinkedIn has no native ad set entity, so campaign-level and ad-set-level queries return the same data ([LinkedIn campaign and account structure](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaigns)).
* **Company breakdown labels can be raw URNs.** LinkedIn's organizations lookup requires that the connecting user be a member of the organization. Companies without that membership fall back to the raw URN as the label.
* **Token activation delay.** After OAuth, LinkedIn's API can take up to roughly a minute to accept the new token. The connector retries the ad-account list call multiple times during this window; if LinkedIn takes longer, data source creation can fail and a retry is required.
* **Token expiry.** OAuth tokens occasionally expire and require re-authorization via the connections list.
* **Today's end date is omitted.** Reports for date ranges ending today omit the end-date field to prevent partial-day data contamination.

## API references

* [LinkedIn Marketing API — Ad analytics reporting](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting)
* [Ad analytics pivots and breakdowns](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/ads-reporting?tabs=curl#analytics-finder)
* [Campaign and account structure](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads/account-structure/create-and-manage-campaigns)
* [Conversion tracking](https://learn.microsoft.com/en-us/linkedin/marketing/integrations/ads-reporting/conversion-tracking)

## See also

* [How to connect LinkedIn Ads to Adriel](/data-sources/g-n/linkedin-ads/how-to-connect) (paired how-to)
* [LinkedIn Organic data reference](/data-sources/g-n/linkedin-organic/data-reference) — for organic Page metrics
* [Meta Ads data reference](/data-sources/g-n/meta-ads/data-reference) — for paid social attribution comparison