---
title: "Meta Ads campaign leaderboard + totals"
method: GET
path: "/meta-ads/campaigns/{campaign_id}/rollups"
tags: ["Meta Ads"]
---

# Meta Ads campaign leaderboard + totals

`GET /meta-ads/campaigns/{campaign_id}/rollups`

## Request

- Base URL: `https://api.reacherapp.com/public/v1`
- URL: `https://api.reacherapp.com/public/v1/meta-ads/campaigns/{campaign_id}/rollups`
- Auth: API key in header `x-api-key` and API key in header `x-shop-id`

The Creators-tab view for one campaign: five summary-card totals (attributed GMV, impressions/views, GMV per video, ad spend, commission owed) plus a per-creator leaderboard with each creator's attributed GMV, ad spend, impressions, distinct attributed ads, lifetime vs. outstanding commission, and Partnership-ad whitelist status. Every metric is Meta-side (from the attribution ledger) — TikTok organic stats are not mixed in. All cents are in the shop's Meta ad account currency (echoed as `currency`). Single shop only.

## Path parameters

- `campaign_id` string, required

## Query parameters

- `page` integer: 1-indexed leaderboard page.
- `page_size` integer: Leaderboard rows per page. Defaults to the maximum so a caller that ignores paging still receives a full page; read `creator_total` / `total_pages` to walk the rest.

## Response `200`

Successful Response

- MetaAdsCampaignRollupsResponse: Summary-card totals + ranked creator leaderboard for one campaign.
  - `totals` MetaAdsRollupTotals: 5 summary-card totals for the campaign Creators tab. Every metric is Meta-side (from the attribution ledger); TikTok organic stats are not mixed in.
    - `gmv_cents` integer: Attributed purchase-conversion value, cents.
    - `views` integer: Sum of Meta ad impressions.
    - `gmv_per_video_cents` integer: gmv_cents / distinct attributed Meta ads (0 when no ads).
    - `ad_spend_cents` integer
    - `commission_owed_cents` integer: Unpaid commission (ledger status pending+approved), cents.
    - `ads` integer: Distinct attributed Meta ads across the campaign.
  - `creators` MetaAdsLeaderboardRow[]: One page of the ranked leaderboard.
    - `creator_id` string, required
    - `rank` integer: Position on the whole leaderboard, assigned before any search filter — a filtered page keeps true board positions.
    - `creator_handle` string, nullable
    - `creator_name` string, nullable
    - `avatar_url` string, nullable
    - `instagram_handle` string, nullable: Normalized Instagram handle, when the creator stored one.
    - `invite_status` 'pending' | 'invited' | 'accepted' | 'active', required
    - `gmv_cents` integer
    - `ad_spend_cents` integer
    - `payout_earned_cents` integer: Lifetime commission earned across all ledger statuses, cents.
    - `payout_outstanding_cents` integer: Unpaid portion only (ledger status pending+approved), cents.
    - `payout_payable_cents` integer: The part of payout_outstanding_cents keyed by a TikTok account the creator is verified to own, cents — what a payout would actually transfer. Lower than outstanding when some earnings sit under a TikTok account not yet linked to this creator.
    - `payout_status` string: ready (payable money and a Stripe account to receive it) | awaiting_creator (payable money, creator has not connected Stripe) | awaiting_verification (earnings under a TikTok account not yet verified as this creator's) | paid (nothing outstanding).
    - `videos` integer: Distinct attributed Meta ads.
    - `views` integer: Sum of Meta ad impressions.
    - `whitelist_granted` boolean, nullable: Partnership-ad whitelist status for this brand: true=approved, false=not approved, null=unknowable (creator has no linked Instagram).
    - `whitelist_status` union: Finer lifecycle: no_instagram | not_requested | pending | approved | revoked | unknown.
      - 'no_instagram' | 'not_requested' | 'pending' | 'approved' | 'revoked' | 'unknown'
      - string
  - `creator_total` integer: Creators on the campaign across all pages, unaffected by search.
  - `filtered_total` integer: Creators matching the request's search across all pages — the paging denominator. Equals creator_total when no search is set.
  - `page` integer: 1-indexed page these creators came from.
  - `page_size` integer: Rows requested per page.
  - `total_pages` integer: Pages available at this page_size.
  - `pagination` PublicApiCorePaginationPaginationMeta: Pagination metadata returned in responses.
    - `total_count` integer, required
    - `page` integer, required
    - `page_size` integer, required
    - `total_pages` integer, required
  - `currency` string, nullable: ISO 4217 currency of the shop's connected Meta ad account (all cents amounts are in this currency). Null when no ad account is connected or the currency is unknown.

## Other responses

- `422`: Validation Error

## Changes

> 76 revisions in range; 1 not diffed.

- **2026-09-19** `291230805105`: 4 warning, 3 info
  - added the new `accepted` enum value to the `creators/items/invite_status` response property for the response status `200`
  - added the new `active` enum value to the `creators/items/invite_status` response property for the response status `200`
  - added the new `invited` enum value to the `creators/items/invite_status` response property for the response status `200`
  - added the new `pending` enum value to the `creators/items/invite_status` response property for the response status `200`
  - …3 more
- **2026-09-11** `02635188ace8`: 2 info
  - added the optional property `creators/items/payout_payable_cents` to the response with the `200` status
  - added the optional property `creators/items/payout_status` to the response with the `200` status

[Operation history](https://skmtc.dev/reacherapp/apis/reacher-data-api/changes/meta-ads/campaigns/:campaign_id/rollups/get.md)

---

[API](https://skmtc.dev/reacherapp/apis/reacher-data-api.md) - [All operations](https://skmtc.dev/reacherapp/apis/reacher-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/reacherapp/apis/reacher-data-api/revisions/63ce74b30b5a?raw)