--- title: Ad Groups Report framework: Apple Ads Platform API role: symbol role_heading: Web Service Endpoint platforms: [apple ads platform api 1.0+] path: apple-ads-platform-api/get-app-ad-group-reports --- # Ad Groups Report Retrieve performance metrics for ad groups. ## URL POST https://api.ads.apple.com/v1/reports/apps/adgroups/query ## Header Parameters X-Ap-Context: ## Response Codes 200 OK: Successful response. Returns AppsAdGroupReportResponse (result: AppsAdGroupResultContainer). 400 Bad Request: Bad Request. Returns ErrorResponse. 401 Unauthorized: Unauthorized. 403 Forbidden: Forbidden. 404 Not Found: Not Found. Returns ErrorResponse. 429 Too Many Requests: Rate Limit Exceeded. Returns ErrorResponse. 500 Internal Server Error: Internal Server Error. Returns ErrorResponse. ## Discussion 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. | | | | | 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. | | | | Payload Examples ## See Also - [Campaigns Report](apple-ads-platform-api/get-app-campaign-reports.md) - [Ads Report](apple-ads-platform-api/get-app-ad-reports.md) - [Keywords Report](apple-ads-platform-api/get-app-keyword-reports.md) - [Search Terms Report](apple-ads-platform-api/get-app-search-term-reports.md)