Ad Groups Report

Retrieve performance metrics for ad groups.

URL

POST https://api.ads.apple.com/v1/reports/apps/adgroups/query

Header Parameters

Name	Type	Description
`X-Ap-Context` Required	string

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`AppsAdGroupReportResponse`	Successful response. Returns AppsAdGroupReportResponse (`result`: AppsAdGroupResultContainer).
400	Bad Request Content-Type: application/json	`Error`	Bad Request. Returns ErrorResponse.
401	Unauthorized Content-Type: application/json	`Error`	Unauthorized.
403	Forbidden Content-Type: application/json	`Error`	Forbidden.
404	Not Found Content-Type: application/json	`Error`	Not Found. Returns ErrorResponse.
429	Too Many Requests Content-Type: application/json	`Error`	Rate Limit Exceeded. Returns ErrorResponse.
500	Internal Server Error Content-Type: application/json	`Error`	Internal Server Error. Returns ErrorResponse.

Discussion

Ad group reports return one row per ad group. Each row contains a metadata object with ad group identifiers (including campaignId), totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity.

Every apps report request requires a campaignId filter; optionally add adGroupId in the filters array to scope results further. Use groupBy to split metrics along a dimension: each dimension value produces its own row within the ad group’s result.

See Filter for the full set of supported comparison operators.

Request Body

See AppsReportingRequest.

groupBy Dimensions

deviceClass, ageRange, gender, countryCode, adminArea, locality, storefront, countryOrRegion

Granularity constraints follow the usual date range rules, from a 7-day lookback for HOURLY to a 90-day-old end date for MONTHLY.

Granularity	Constraint
`DAILY`	Date range start must be within the last 90 days. Date range must be greater than one day.
`HOURLY`	Date range start must be within the last 7 days.
`WEEKLY`	Date range start within the last 365 days. End date must be at least 14 days in the past.
`MONTHLY`	End date must be at least 90 days in the past.

To request a single day of data, omit granularity entirely. For a single-day request, the response returns results in totalMetrics only, since there is no granularMetrics breakdown to compute.

Filtering by campaignId, selecting a timezone of ORTZ or UTC, and narrowing the fields array all help keep ad group report responses manageable.

Constraint	Detail
Filter by `campaignId`	Recommended to scope results and reduce response size.
Timezone	Use `ORTZ` (reporting timezone) or `UTC`.
Fields selection	Use the `fields` array to request only specific metric columns.