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

# Ad analytics

> Daily ad-performance rows per channel — Facebook, Google, LinkedIn, TikTok, Microsoft, Reddit, Taboola, AdRoll, Whop, ChatGPT Ads, and X.

## What it is

Ad analytics is **one dataset per channel** — not a single unified dataset — because each channel's daily-performance table has a different shape (different metrics, different metric-date column). Each row is one day of performance for one ad-hierarchy entity.

* **Grain:** one row per entity per day — the `cometly_*_id` columns plus the metric date.
* **Windowed on:** the channel's **metric date** (a local calendar date — see below).
* **Path segment:** `<channel>_ad_analytics` (for example `facebook_ad_analytics`).

Each channel's columns are listed in the tabs below.

### Identity columns

Every channel exposes its ad hierarchy as IDs only (never names). Each level carries:

* `cometly_<level>_id` — **Locked.** Cometly's internal ID; part of the grain and the key for joining to [Raw touchpoints](https://docs.cometly.com/data-warehouse/datasets/raw-touchpoints.md) and [Attributed conversions](https://docs.cometly.com/data-warehouse/datasets/attributed-conversions.md).
* `platform_<level>_id` — **Optional.** The platform's own ID. Selecting it joins that level's entity table on demand, so the join cost is only paid when you want it. May be null.

The hierarchy levels differ by channel (for example LinkedIn uses campaign group → campaign → creative). Resolve names on your side from these IDs. See [Column conventions](https://docs.cometly.com/data-warehouse/overview.md#column-conventions).

### Dates and restatement

Unlike every other dataset, ad analytics windows on a **local calendar date**, not a UTC timestamp. Cometly matches your picked dates **literally** against the channel's metric date and makes **no timezone conversion** — the same behavior as the ads manager. Which timezone that date is in depends on the channel:

| Metric date timezone | Channels | Effect |
| - | - | - |
| **Space timezone** | Facebook, LinkedIn, TikTok, Reddit, Taboola, AdRoll, Whop, ChatGPT Ads | Picked dates match exactly. |
| **Ad-account timezone** | Google, Microsoft, X | Picked dates are approximate — the window can be off by up to a day at the edges. |

> [!WARNING]
>
> **Recent days may still change.** Ad platforms restate recent days' numbers. A recurring run
> re-exports its full window with current values, so recent days converge across runs — but a day
> restated *after* it leaves the window is not re-exported. For a full refresh, run a one-time export.

> [!NOTE]
>
> Hourly cadence is allowed (the tables refresh through the day, so hourly delivers the freshest
> restatements) but its trailing window is capped at **7 days** for ad-analytics datasets, versus 14
> for other datasets. Daily (up to 90 days) and one-time are unchanged.

## Columns by channel

> [tab] Facebook
>
> Path segment `facebook_ad_analytics`. Metric date column `metric_date_local` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad set | `cometly_adset_id` | `platform_adset_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `delivery`, `amount_spent`, `impressions`, `link_clicks`, `clicks`, `video_view`.
>
> **Reported conversions** (all optional): `reported_purchases`, `reported_leads`, `reported_add_to_cart`, `reported_initiate_checkout`, `reported_complete_registration`, `reported_contact`, `reported_schedule`, `reported_start_trial`, `reported_subscribe`, `reported_view_content`, `reported_search`, `reported_add_payment_info`, `reported_add_to_wishlist`, `reported_landing_page_view`.
>
> **Reported value** (all optional): `reported_revenue`, `reported_leads_value`, `reported_add_to_cart_value`, `reported_initiate_checkout_value`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] Google
>
> Path segment `google_ad_analytics`. Metric date column `metric_date_google` (**Locked**, ad-account timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`, `ctr`, `interactions`, `interaction_rate`, `video_views`, `video_view_rate`.
>
> **Averages** (all optional): `average_cpm`, `average_cpc`, `average_cost`, `average_cpe`, `average_cpv`.
>
> **Conversions** (all optional): `conversions`, `all_conversions`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] LinkedIn
>
> Path segment `linkedin_ad_analytics`. Metric date column `metric_date` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign group | `cometly_campaign_group_id` | `platform_campaign_group_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Creative | `cometly_creative_id` | `platform_creative_id` |
>
> **Performance** (all optional): `cost`, `clicks`, `impressions`, `video_views`.
>
> **Conversions & leads** (all optional): `conversions`, `conversion_value`, `leads`, `registrations`, `one_click_lead_form_opens`, `form_completion_rate`, `external_website_post_view_conversions`, `external_website_post_click_conversions`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] TikTok
>
> Path segment `tiktok_ad_analytics`. Metric date column `metric_date_local` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `amount_spent`, `impressions`, `clicks`.
>
> **Reported conversions** (all optional): `reported_purchases`, `reported_revenue`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] Microsoft
>
> Path segment `microsoft_ad_analytics`. Metric date column `metric_date_microsoft` (**Locked**, ad-account timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`, `video_views`.
>
> **Conversions** (all optional): `conversions_qualified`, `view_through_conversions_qualified`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] Reddit
>
> Path segment `reddit_ad_analytics`. Metric date column `metric_date_reddit` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`, `reddit_video_views`.
>
> **Conversions** (all optional): `reddit_reported_roas`, `conversion_purchase_total_value`, `conversion_page_visit_view`, `conversion_sign_up_views`, `conversion_lead_views`, `conversion_purchase_views`, `conversion_page_visit_clicks`, `conversion_sign_up_clicks`, `conversion_lead_clicks`, `conversion_purchase_clicks`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] Taboola
>
> Path segment `taboola_ad_analytics`. Metric date column `metric_date_taboola` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> Campaign, ad-group, and ad IDs can be null on Taboola rows, so their platform IDs may come back null.
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] AdRoll
>
> Path segment `adroll_ad_analytics`. Metric date column `metric_date_adroll` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> Campaign, ad-group, and ad IDs can be null on AdRoll rows, so their platform IDs may come back null.
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`.
>
> **Conversions** (all optional): `conversions`, `click_throughs`, `view_throughs`, `revenue`, `click_revenue`, `view_revenue`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] Whop
>
> Path segment `whop_ad_analytics`. Metric date column `metric_date_whop` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> A Whop "account" is a Whop company (`biz_xxx`); that id is the `platform_account_id` and also doubles as the `company_id` required by Whop's Conversions API.
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`, `reach`.
>
> **Results** (all optional): `whop_result_count`, `whop_result_label_key`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] ChatGPT Ads
>
> Path segment `chatgpt_ad_analytics`. Metric date column `metric_date_chatgpt` (**Locked**, space timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> Platform ids are OpenAI's string ids (`cmpn_…`, `adgrp_…`, `ad_…`). Spend is converted into the space currency; OpenAI reports it in the ad account's currency and settles it 7 to 8 hours after the clicks, so recent days are restated by the morning backfills.
>
> **Performance** (all optional): `spend`, `clicks`, `impressions`.
>
> **OpenAI attribution** (all optional): `platform_conversions`, `platform_attributed_sales` (OpenAI's own click-through plus view-through attribution for the ad, as its Ads Manager reports it; Cometly's attributed conversions live in the event datasets).
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).

> [tab] X
>
> Path segment `x_ad_analytics`. Metric date column `metric_date_x` (**Locked**, ad-account timezone).
>
> **Identity**
>
> | Level | Cometly ID (Locked) | Platform ID (Optional) |
> | - | - | - |
> | Account | `cometly_account_id` | `platform_account_id` |
> | Campaign | `cometly_campaign_id` | `platform_campaign_id` |
> | Ad group | `cometly_adgroup_id` | `platform_adgroup_id` |
> | Ad | `cometly_ad_id` | `platform_ad_id` |
>
> **Performance** (all optional): `spend`, `clicks`, `x_url_clicks`, `impressions`, `x_video_views`, `x_engagements`.
>
> **Conversions** (all optional): `conversion_purchase_total_value`, `conversion_purchases`, `conversion_sign_ups`, `conversion_site_visits`, `conversion_downloads`, `conversion_custom`.
>
> **Timestamps** (all optional): `created_at`, `updated_at` (last restated).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.