insights breakdown

It is the reporting operation that turns one campaign total into many rows - impressions split by audience, delivery surface, device or hour. Each platform draws the same idea with its own vocabulary:

• Meta Marketing API - breakdowns available by country, region and metro via the insights edge; dimensions include publisher_platform, platform_position, age, gender, country, region, impression_device or product_id.
• TikTok Business API & Ads Manager - the Smart+ material report alone enumerates roughly 862 metric keys, and time breakdowns go down to hourly.
• X (Twitter) Ads API - synchronous and asynchronous analytics with granular engagement, billing, video and conversion metrics.

The dimension list you choose determines both the row count and the API cost of every pull.

Breakdown support decides whether a question is answerable at all from platform reporting.

• Dimension availability varies. Meta offers publisher_platform and impression_device; if your hypothesis needs device-level delivery, a source without those dimensions cannot serve it at any price.
• Metric-key sprawl is real. TikTok's Smart+ material report alone lists roughly 862 metric keys - selecting fields carelessly returns unusable sparsity.
• Time grain caps temporal analysis. Only sources with hourly breakdowns can resolve intraday pacing; daily-grain sources cannot recover it later.
• Cost scales with slicing. Every added dimension multiplies rows fetched, which matters on rate-limited marketing APIs.

Of the 1,744 datasets in this catalog, 574 offer an official API - these ad platforms are the case where API design is the dataset.

1. Enumerate the dimensions before the metrics. Confirm the exact breakdown names - Meta's publisher_platform, platform_position, age, gender, country, region, impression_device, product_id - rather than assuming parity across platforms.

1. Count the metric keys you will actually use. With roughly 862 keys in TikTok's Smart+ material report, pin a shortlist or responses become unmanageable.

1. Verify minimum time grain. Ask whether hourly time breakdowns exist (TikTok's do); intraday questions die on daily-only endpoints.

1. Check sync versus async delivery. X's Ads API offers both synchronous and asynchronous analytics - large breakdown pulls usually want the async route.

1. Reconcile sliced totals against campaign totals. If breakdown rows do not sum to the headline metric, attribution rules differ and comparisons will mislead.

Adjacent reporting concepts: - campaign object hierarchy — The nested entity tree every major ad platform exposes through its API - advertiser/account at the root, then campaigns and progressively finer units down to individual ads, keywords or creatives.