Ads Report

Retrieve performance metrics for ads.

URL

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

Header Parameters

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

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`AppsAdReportResponse`	Successful response. Returns AppsAdReportResponse (`result`: AppsAdResultContainer).
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 reports return one row per ad. Each row contains a metadata object with ad identifiers (including campaignId and adGroupId), totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity.

Filter by the required campaignId in the filters array, optionally narrowed further by adGroupId.

See Filter for the full set of supported comparison operators.

Request Body

See AppsReportingRequest.

groupBy Dimensions

countryOrRegion

The AD entity supports only the countryOrRegion groupBy dimension. deviceClass, ageRange, gender, countryCode, adminArea, and locality are not supported.

Ad reports follow the standard date range rules per granularity, except HOURLY isn’t available at the ad level.

Granularity	Constraint
`DAILY`	Date range must span 90 days or less.
`HOURLY`	Not supported for the `AD` entity.
`WEEKLY`	Date range must span at least 14 days.
`MONTHLY`	Date range must span at least 90 days.

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.

Only DAILY granularity or coarser is available for ads, and either ORTZ or UTC timezones are accepted.

Constraint	Detail
HOURLY granularity	Not available for ads. Use `DAILY` as the finest granularity.
Timezone	Use `ORTZ` (reporting timezone) or `UTC`.