Ad Groups Report (Brands)
Retrieve performance metrics for Apple Maps ad groups.
URL
POST https://api.ads.apple.com/v1/reports/business-brands/adgroups/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | BrandsAdGroupReportResponse | Successful response. Returns BrandsAdGroupReportResponse ( |
| 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
Brand 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.
Filter by campaignId or adGroupId in the filters array to scope results. 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
The groupBy array supports three dimensions for ad groups: device class, business location, and ad placement.
Dimension | Description |
|---|---|
| Break down metrics by device type ( |
| Break down metrics per business location. |
| Break down metrics by ad placement. |
Each granularity value comes with its own date range restrictions, from a 7-day lookback for HOURLY to a 90-day-old end date for MONTHLY.
Granularity | Constraint |
|---|---|
| Date range start must be within the last 90 days. Date range must be greater than one day. |
| Date range start must be within the last 7 days. |
| Date range start within the last 365 days. End date must be at least 14 days in the past. |
| 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.
Beyond granularity, note that EMPTY_METRICS isn’t supported for business-brands, filtering by campaignId keeps responses manageable, and only ORTZ or UTC timezones are accepted.
Constraint | Detail |
|---|---|
| Not supported for |
Filter scope | Always filter by |
Timezone | Use |