Ad Report

Ranks your paid campaigns by what they spend, and shows what came back.

Use it when you are deciding which campaign to scale, pause or rebuild — or when someone asks whether the ad budget is paying for itself.

The question it answers: where is the ad money going, and which of it comes back as customers?

Two ways to call it

What you get

Where the numbers come from. The ad platforms themselves (Google, Facebook, LinkedIn and Reddit) supply spend and clicks. Revenue is joined back to a click through its gclid — Google's click identifier — and that join is thin, which is why the leaderboard ranks by spend, not revenue: spend is complete, joined revenue is not. Product events are campaign-level only (empty at the ad_group, ad and keyword levels) and cover first-touch paid payers (Paid Search or Paid Social); those counts are exact unique people over the report's range, not estimates or samples, and they are aggregate only: the report returns no personally identifiable information (PII). The Precision notes at the end of this page give the exact warehouse wording.

Lifetime economics are Google-only and campaign-level. Every row carries the LTV / CAC / ROAS keys so the response shape never varies, but they are null outside level=campaign and on non-Google rows — including on the default cross-platform call, where the Google rows among them are populated and the rest are null. A null here means "we cannot compute this for this row", not "zero".

Reddit accounts and attribution

Reddit supports campaign, ad group and ad levels. Reports include only the account currently connected to the workspace, including cross-platform calls, comparisons and chart series. An account_id filter cannot expose a previously connected account; no connection means no Reddit rows.

First-party Reddit revenue attaches at campaign grain when utm_campaign contains the Reddit campaign ID. Bare click IDs or campaign names do not match spend. Ad group and ad rows keep platform-reported purchases and spend, but have no first-party conversion credit. Reddit has no keyword level or click map; choosing a journey model does not create Reddit multi-touch attribution.

Two things that do not follow your range

landing_pages is a fixed trailing-90-day snapshot. It is workspace-wide and Google-only, ignores from / to, level, entity and account_id, and comes back even when rows is empty — so a two-day range returns the same landing_pages block as a thirty-day one. Its g_clicks is a 90-day figure and obs_gclid_clicks counts gclid pageviews (a reload inflates it). Never reconcile either against the windowed rows.

level=keyword sees keyword-matched Search traffic only. It reads Google's keyword_view, and impressions or clicks served through Display expansion carry no keyword, so they are absent at this level. When a Search campaign has Display expansion on, keyword rows can sum to a few percent of the campaign (3% of impressions on one live week, 86% the week before). level=ad_group reconciles to the campaign exactly; read a keyword-vs-campaign gap as non-keyword serving, not as missing data.

Full window vs fair window

Conversions land days after the click, so a campaign that started spending yesterday looks terrible on the full window: it has all of the spend and almost none of the revenue.

• Full window — every day in your range, spend and revenue alike.
• Fair window — the same metrics with the most recent days clipped off, because those days are too new for their conversions to have arrived yet. The single form returns the date that window starts as measurement_start.

Compare like with like: judge a young campaign on its fair-window figures and a mature one on either.

Parameters

The series array — granularity

granularity is purely additive: rows is unchanged, and omitting it returns exactly the previous response. Each point carries spend, revenue and reported_conversion_value.

Buckets are labelled with their start date (Monday for weekly), oldest first, and the trailing bucket may be partial — compare it against range.to.

Do not add the buckets up to get the range totals — rate metrics are recomputed per bucket. Use rows for totals.

Use Keyword Report for the organic-search counterpart.

Ranking, totals and comparison

Three group-form parameters, each independently opt-in. Omit all three and the response is exactly the one you got before they existed — no totals, no totals_meta, no prior.

Re-ranking the leaderboard — order_by

order_by is a closed enum per report — the legal columns are listed in the order_by dropdown of the API panel above. Omit it and you keep the default spend ranking, unchanged. order_dir is asc or desc, defaults to desc, and does nothing on its own.

• The re-rank applies to the complete leaderboard, before limit — a campaign the spend ranking buried below the limit surfaces, rather than the same top-20 reshuffled.
• The three LTV columns are sortable: ltv-by-campaign is read once for every Google campaign before the spend ranking, so their values exist across the complete set. events is not sortable — it is filled only for the rows you get back.
• Nulls sort last in both directions. A non-Google row has no avg_ltv_cents; that is unknown, not worst.
• Ties always break on the level's identity (campaign_id, ad_group_id, ad_id or the keyword) ascending, so the order is total and two equal-spend campaigns never swap between calls.

Whole-set totals — totals

totals=true adds a totals object covering the complete leaderboard before limit — every entity at the selected level, not just the returned ones — plus a totals_meta sidecar. Anything other than true/false is a 400; nothing is coerced.

Rates are recomputed from their bases over the whole set, never summed or averaged across rows: avg_ltv_cents is whole-set lifetime revenue over whole-set customers.

totals_meta.upper_bound is empty on this report — every summed column partitions cleanly across ad entities.

totals_meta.omitted names the columns deliberately left out, so their absence reads as a decision rather than a bug:

A fields trim trims totals with it: neither totals nor prior ever describes a column the response itself does not carry.

Comparing against a prior window — compare_to

compare_to attaches a prior object to each row, measured over a second window:

• prior: null means the entity did not exist in that window. That is a different claim from a prior object of zeros, which means present and measured zero; conflating them reports a brand-new campaign as flat.
• Prior-only rows are not introduced. A campaign that spent then and is paused now does not appear — the list is still the current window's.
• The prior window differs only in its dates: same workspace, same level, platform and account_id, same fields.
• Independent of totals. A nested totals.prior appears only when both are set.
• compare_to roughly doubles the cold-path work — every query this report issues runs a second time over the prior window, and that includes a second read of the un-windowed ltv-by-campaign view, whose lifetime figures are identical in both windows. Only Page Report memoizes its ranked set; this one does not.

Trimming the response — fields

fields is a comma-separated list of response blocks. Omit it and you get every block — it only ever narrows a response, never widens one, so every existing call keeps its exact shape.

?fields=ltv                        → campaign rows keep only lifetime economics
?fields=performance                → the spend leaderboard, no LTV / landing pages
?entity=123&fields=ltv             → that campaign's LTV block alone

Rules that bite:

• The ids and names are not a block. campaign_id, campaign_name, ad_group_id, ad_id, keyword, platform, account_id, level and range are row identity — they survive every trim and cannot be named in fields. On the single form, entity is identity but row is not: it is the performance payload, so ?fields=ltv omits it.
• ltv is campaign-level and Google-only. Every row carries the six LTV keys so the response shape does not vary by level, but they are null outside level=campaign and on non-Google rows — including on the default cross-platform call, where the Google rows among them are populated and the rest are null.
• Trimming does not guarantee a query saved per block. The leaderboard query is also what resolves an addressed entity, so it runs whatever you ask for — ?fields=ltv still issues it, then keeps only the LTV columns. The Precision notes name it.
• Empty, duplicated, unknown, and * are all 400s — fields=, fields=ltv,ltv, fields=nope, fields=*. The error names the legal blocks.
• granularity is independent. The series array is not a block.
• fields never lowers the scopes the endpoint requires.

Segmenting the series — series_by

Supply series_by alongside granularity (group form only) to split the series by one dimension instead of returning scope-level totals. series then holds one point per (bucket × segment), each carrying key — the segment value — so the response can feed a stacked or multi-line chart directly.

Accepted here: campaign.

granularity=weekly                 → [{ date, <metrics> }, …]
granularity=weekly&series_by=campaign  → [{ date, key, <metrics> }, …]

Notes that bite:

• A source view that has no breakdown for the requested dimension is dropped from the segmented series, not smeared across every segment — copying a scope-level total onto each segment would read as per-segment data and be wrong. So a segmented series can carry fewer metric keys than the flat one.
• Rows whose dimension value is blank are skipped: an unnamed series cannot be labelled or filtered by the caller.
• An unrecognised series_by returns an empty series (not an error, and not a silent fallback to the flat series).
• Segment values may contain spaces (search queries, campaign names) — key is the full value.
• rows is unaffected. Do not sum segmented buckets to get range totals; use rows.