Delivery dimensions
Break ad performance down by audience and placement, independent of creative.
A delivery dimension breaks ad performance down by who saw the ad and where it ran — independent of the creative. You request one by setting groupBy on Fetch ad insights to a delivery dimension instead of a creative dimension like creative or name. The response returns one row per dimension value (e.g. one row per age bracket) with summed metrics.
Available dimensions
| Dimension | Platforms | What it splits by |
|---|---|---|
age | Meta, TikTok | Audience age bracket |
gender | Meta, TikTok | Audience gender |
publisher_platform | Meta only | App / network: Facebook, Instagram, Messenger, Audience Network |
platform_position | Meta only | Position within the app: feed, stories, reels, search… |
country | Meta only | Viewer country, as an ISO 3166-1 alpha-2 code (US, GB, CA…) |
placement | TikTok only | Where the ad ran |
publisher_platform and platform_position are the Meta way of describing placement; TikTok collapses both into a single placement. country has no TikTok equivalent. Sending a Meta-only dimension for TikTok (or placement for Meta) returns 400:
groupBy "publisher_platform" is not supported for TikTok. Use "placement" instead.groupBy "platform_position" is not supported for TikTok. Use "placement" instead.groupBy "country" is not supported for TikTok.groupBy "placement" is not supported for Meta. Use "publisher_platform" or "platform_position" instead.
Dimension values
Each response row carries a field named after the groupBy (e.g. "age": "25-34") holding its dimension value — creativeKey is set to the same value. Meta returns humanized values (25-34, female, instagram, feed) and ISO country codes for country (US; unknown when Meta can't attribute a country); TikTok returns raw enums (AGE_25_34, FEMALE, PLACEMENT_TIKTOK). Use the platform's own casing when filtering.
Example
{
"platform": "facebook",
"adAccountId": "01JAN78QQ6BX9ZPKA6A8JWA6G1",
"workspaceId": "01JF0X2QDQ648YE4J1M56EFBR4",
"datePreset": "last_30d",
"groupBy": "age"
}Filtering by a delivery dimension
A delivery filter (age, gender, publisherPlatform, platformPosition, country, placement — note the camelCase, unlike the snake_case groupBy values) only takes effect when groupBy is the matching delivery dimension. For example, an age filter applies only when groupBy is age (or gender — they share a breakdown). Sending a delivery filter without the matching groupBy returns 400, e.g.:
filters: filter "age" requires the report to be grouped by a matching delivery dimension. Group by Age or Gender to use this filter.filters: filter "country" requires the report to be grouped by a matching delivery dimension. Group by Country to use this filter.
The filter value is a dimension value string or an array of them (array = matches any), compared exactly: { "field": "age", "type": "is", "value": ["18-24", "25-34"], "metric": false, "id": "f1", "namingConventionId": "" }.
Period-over-period
Delivery groupBy composes with popRangeType: the prior-period rows in popData.insights are broken down by the same dimension, and popData.popRateOfChange is keyed by dimension value — so you get per-bracket / per-platform rate-of-change, not an account-level one.
Relation to creative grouping
Creative dimensions (name, creative, body_asset, title_asset, link_url_asset, campaign_name, adset_name) group ads by what they are. Delivery dimensions group by how they were delivered. You pick exactly one groupBy per request — the two are not combined in a single call.
