---
title: "Retrieve ad report"
method: GET
path: "/ad_reports"
tags: ["Ad reports"]
---

# Retrieve ad report

`GET /ad_reports`

Performance report for a company, ad campaigns, ad groups, or ads. Always returns aggregate `summary` totals summed across the scope. Set `granularity` to additionally get a time series, or set `breakdown` (`campaign`/`ad_group`/`ad`) to additionally get per-entity rows inside the requested scope. Exactly one of `companyId`, `adCampaignIds`, `adGroupIds`, or `adIds` must be provided.

Required permissions:
 - `ad_campaign:stats:read`

## Query parameters

- `ad_campaign_ids` string[], nullable — Scope the report to these ad campaigns (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adGroupIds`, and `adIds`.
- `ad_group_ids` string[], nullable — Scope the report to these ad groups (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adCampaignIds`, and `adIds`.
- `ad_ids` string[], nullable — Scope the report to these ads (max 100); stats are summed across them. Mutually exclusive with `companyId`, `adCampaignIds`, and `adGroupIds`.
- `breakdown` 'campaign' | 'ad_group' | 'ad' — Entity level to group an ad report by.
- `company_id` string, nullable — The unique identifier of a company. Mutually exclusive with `adCampaignIds`, `adGroupIds`, and `adIds`. Use with `breakdown` to fan out across every campaign, ad group, or ad in the company without paging.
- `currency` string, nullable — ISO 4217 currency code to report `spend` in. Defaults to the company's ads reporting currency.
- `from` string, date-time, required — Inclusive start of the reporting window.
- `granularity` 'hourly' | 'daily' | 'weekly' | 'monthly' — Bucket size for external ad stat rows.
- `to` string, date-time, required — Inclusive end of the reporting window.

## Response `200`

A successful response

- AdReport — An ads performance report. Always returns a summary. The `granularity` field contains a per-bucket time series when the `granularity` arg is set; the `breakdown` field contains per-entity rows when the `breakdown` arg is set.
  - `breakdown` object[], nullable, required — Per-entity rows over the date range. `null` when the `breakdown` arg on `adReport` is omitted; otherwise contains one row per ad campaign, ad group, or ad inside the requested scope at the requested level.
    - `granularity` object[], nullable, required — Per-bucket time series for this entity over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).
      - `bucket_start` string, date-time, required — The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.
      - `clicks` integer, required — Clicks in this bucket.
      - `granularity` 'hourly' | 'daily' | 'weekly' | 'monthly', required — Bucket size for external ad stat rows.
      - `impressions` integer, required — Impressions in this bucket.
      - `reach` integer, required — Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).
      - `result_count` integer, nullable, required — Count of the primary optimization result in this bucket.
      - `result_label_key` 'app_installs' | 'messaging_conversations_started' | 'post_engagement' | 'event_responses' | 'impressions' | 'website_purchases' | 'landing_page_views' | 'leads' | 'link_clicks' | 'quality_calls' | 'appointments_booked' | 'messaging_purchases' | 'page_likes' | 'instagram_profile_visits' | 'reach' | 'reminders_set' | 'new_subscribers' | 'video_views' | 'registrations' | 'content_views' | 'searches' | 'adds_to_cart' | 'adds_to_wishlist' | 'adds_of_payment_info' | 'checkouts_initiated' | 'website_schedules' | 'website_submit_applications' | 'website_trials_started' | 'website_subscriptions' | 'website_contacts' | 'website_donations' | 'website_find_locations' | 'website_product_customizations' | 'custom', required — Types of optimization results tracked from external ad platforms
      - `result_label_override` string, nullable, required — Advertiser-defined label for the result when `resultLabelKey` is `custom`.
      - `spend` number, required — Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.
      - `spend_currency` 'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau', required — The available currencies on the platform
      - `stat_date` string, date-time, required — The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.
      - `stat_hour` integer, nullable, required — Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.
    - `id` string, required — Tag of the entity (ad campaign, ad group, or ad).
    - `level` 'campaign' | 'ad_group' | 'ad', required — Entity level to group an ad report by.
    - `name` string, nullable, required — Display name of the entity, when available.
    - `summary` object, required — Aggregate totals and rates for this entity over the date range.
      - `click_through_rate` number, required — Click-through rate (clicks / impressions).
      - `clicks` integer, required — Total clicks over the date range.
      - `cost_per_click` number, required — Cost per click in the requested reporting currency.
      - `cost_per_mille` number, nullable, required — Cost per thousand impressions in the requested reporting currency.
      - `cost_per_result` number, nullable, required — Spend divided by `resultCount`. Null when there are no results.
      - `frequency` number, nullable, required — Average number of times each reached user saw an ad.
      - `impressions` integer, required — Total impressions over the date range.
      - `reach` integer, required — Unique users reached, deduplicated by the external ad platform.
      - `result_count` integer, nullable, required — Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.
      - `result_label_key` 'app_installs' | 'messaging_conversations_started' | 'post_engagement' | 'event_responses' | 'impressions' | 'website_purchases' | 'landing_page_views' | 'leads' | 'link_clicks' | 'quality_calls' | 'appointments_booked' | 'messaging_purchases' | 'page_likes' | 'instagram_profile_visits' | 'reach' | 'reminders_set' | 'new_subscribers' | 'video_views' | 'registrations' | 'content_views' | 'searches' | 'adds_to_cart' | 'adds_to_wishlist' | 'adds_of_payment_info' | 'checkouts_initiated' | 'website_schedules' | 'website_submit_applications' | 'website_trials_started' | 'website_subscriptions' | 'website_contacts' | 'website_donations' | 'website_find_locations' | 'website_product_customizations' | 'custom', required — Types of optimization results tracked from external ad platforms
      - `result_label_override` string, nullable, required — Advertiser-defined label for the result when `resultLabelKey` is `custom`.
      - `return_on_ad_spend` number, nullable, required — Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.
      - `spend` number, required — Total spend over the date range in the requested reporting currency.
      - `spend_currency` 'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau', required — The available currencies on the platform
  - `granularity` object[], nullable, required — Per-bucket time series over the date range, ordered ascending by `bucketStart`. `null` when the `granularity` arg on `adReport` is omitted; otherwise contains rows at the requested grain (`daily` or `hourly`).
    - `bucket_start` string, date-time, required — The bucket's start time as a real UTC instant. `(statDate, statHour)` resolved in the ad account's reporting timezone — render this in the viewer's local timezone.
    - `clicks` integer, required — Clicks in this bucket.
    - `granularity` 'hourly' | 'daily' | 'weekly' | 'monthly', required — Bucket size for external ad stat rows.
    - `impressions` integer, required — Impressions in this bucket.
    - `reach` integer, required — Unique users reached in this bucket. Always `0` for hourly rows (Meta does not return reach at hourly grain).
    - `result_count` integer, nullable, required — Count of the primary optimization result in this bucket.
    - `result_label_key` 'app_installs' | 'messaging_conversations_started' | 'post_engagement' | 'event_responses' | 'impressions' | 'website_purchases' | 'landing_page_views' | 'leads' | 'link_clicks' | 'quality_calls' | 'appointments_booked' | 'messaging_purchases' | 'page_likes' | 'instagram_profile_visits' | 'reach' | 'reminders_set' | 'new_subscribers' | 'video_views' | 'registrations' | 'content_views' | 'searches' | 'adds_to_cart' | 'adds_to_wishlist' | 'adds_of_payment_info' | 'checkouts_initiated' | 'website_schedules' | 'website_submit_applications' | 'website_trials_started' | 'website_subscriptions' | 'website_contacts' | 'website_donations' | 'website_find_locations' | 'website_product_customizations' | 'custom', required — Types of optimization results tracked from external ad platforms
    - `result_label_override` string, nullable, required — Advertiser-defined label for the result when `resultLabelKey` is `custom`.
    - `spend` number, required — Charged spend in this bucket in the requested reporting currency — the amount billed including platform fees, not the platform-side net spend.
    - `spend_currency` 'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau', required — The available currencies on the platform
    - `stat_date` string, date-time, required — The date these stats cover (midnight UTC). For hourly rows, see `statHour` and `bucketStart`.
    - `stat_hour` integer, nullable, required — Hour of the day in the ad account's reporting timezone (0-23). `null` for daily rows.
  - `summary` object, required — Aggregate totals and rates over the date range.
    - `click_through_rate` number, required — Click-through rate (clicks / impressions).
    - `clicks` integer, required — Total clicks over the date range.
    - `cost_per_click` number, required — Cost per click in the requested reporting currency.
    - `cost_per_mille` number, nullable, required — Cost per thousand impressions in the requested reporting currency.
    - `cost_per_result` number, nullable, required — Spend divided by `resultCount`. Null when there are no results.
    - `frequency` number, nullable, required — Average number of times each reached user saw an ad.
    - `impressions` integer, required — Total impressions over the date range.
    - `reach` integer, required — Unique users reached, deduplicated by the external ad platform.
    - `result_count` integer, nullable, required — Count of the campaign's primary optimization result (purchases, clicks, etc.) — see `resultLabelKey`.
    - `result_label_key` 'app_installs' | 'messaging_conversations_started' | 'post_engagement' | 'event_responses' | 'impressions' | 'website_purchases' | 'landing_page_views' | 'leads' | 'link_clicks' | 'quality_calls' | 'appointments_booked' | 'messaging_purchases' | 'page_likes' | 'instagram_profile_visits' | 'reach' | 'reminders_set' | 'new_subscribers' | 'video_views' | 'registrations' | 'content_views' | 'searches' | 'adds_to_cart' | 'adds_to_wishlist' | 'adds_of_payment_info' | 'checkouts_initiated' | 'website_schedules' | 'website_submit_applications' | 'website_trials_started' | 'website_subscriptions' | 'website_contacts' | 'website_donations' | 'website_find_locations' | 'website_product_customizations' | 'custom', required — Types of optimization results tracked from external ad platforms
    - `result_label_override` string, nullable, required — Advertiser-defined label for the result when `resultLabelKey` is `custom`.
    - `return_on_ad_spend` number, nullable, required — Alias for `purchaseReturnOnAdSpend` — return on ad spend for purchases, as reported by the external ad platform.
    - `spend` number, required — Total spend over the date range in the requested reporting currency.
    - `spend_currency` 'usd' | 'sgd' | 'inr' | 'aud' | 'brl' | 'cad' | 'dkk' | 'eur' | 'nok' | 'gbp' | 'sek' | 'chf' | 'hkd' | 'huf' | 'jpy' | 'mxn' | 'myr' | 'pln' | 'czk' | 'nzd' | 'aed' | 'eth' | 'ape' | 'cop' | 'ron' | 'thb' | 'bgn' | 'idr' | 'dop' | 'php' | 'try' | 'krw' | 'twd' | 'vnd' | 'pkr' | 'clp' | 'uyu' | 'ars' | 'zar' | 'dzd' | 'tnd' | 'mad' | 'kes' | 'kwd' | 'jod' | 'all' | 'xcd' | 'amd' | 'bsd' | 'bhd' | 'bob' | 'bam' | 'khr' | 'crc' | 'xof' | 'egp' | 'etb' | 'gmd' | 'ghs' | 'gtq' | 'gyd' | 'ils' | 'jmd' | 'mop' | 'mga' | 'mur' | 'mdl' | 'mnt' | 'nad' | 'ngn' | 'mkd' | 'omr' | 'pyg' | 'pen' | 'qar' | 'rwf' | 'sar' | 'rsd' | 'lkr' | 'tzs' | 'ttd' | 'uzs' | 'rub' | 'btc' | 'cny' | 'usdt' | 'kzt' | 'awg' | 'whop_usd' | 'xau', required — The available currencies on the platform

## Other responses

- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Not found
- `422` — Verification required
- `429` — Too many requests
- `500` — Internal server error

---

[API](https://skmtc.net/whop/apis/whop-api.md) · [All operations](https://skmtc.net/whop/apis/whop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/whop/whop-api/versions/866821546d67/schema)