AdnovaDocs
Analytics

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

DimensionPlatformsWhat it splits by
ageMeta, TikTokAudience age bracket
genderMeta, TikTokAudience gender
publisher_platformMeta onlyApp / network: Facebook, Instagram, Messenger, Audience Network
platform_positionMeta onlyPosition within the app: feed, stories, reels, search…
countryMeta onlyViewer country, as an ISO 3166-1 alpha-2 code (US, GB, CA…)
placementTikTok onlyWhere 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.