Campaigns Report

Retrieve performance metrics for campaigns.

URL

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

Header Parameters

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

Response Codes

Status	Reason	Type	Description
200	OK Content-Type: application/json	`AppsCampaignReportResponse`	Successful response. Returns AppsCampaignReportResponse (`result`: AppsCampaignResultContainer).
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

Campaign reports return one row per campaign. Each row contains a metadata object with campaign identifiers, totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity.

The campaignId filter is optional for campaign reports. Use filters to scope the report to specific campaigns, or omit it to return all campaigns. Use groupBy to split metrics along a dimension: each dimension value produces its own row within the campaign’s result.

See Filter for the full set of supported comparison operators.

Request Body

See AppsReportingRequest.

groupBy Dimensions

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

Date range requirements vary by granularity: HOURLY and DAILY are capped at 7-day and 90-day spans respectively, while WEEKLY and MONTHLY require spans of at least 14 and 90 days respectively.

Granularity	Constraint
`DAILY`	Date range must span 90 days or less.
`HOURLY`	Date range must span 7 days or less, and the start date must be within the last 365 days.
`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.

Selecting a timezone of ORTZ or UTC and using the fields array to request specific metrics keeps campaign report responses focused.

Constraint	Detail
Timezone	Use `ORTZ` (reporting timezone) or `UTC`.
Fields selection	Use the `fields` array to request only specific metric columns.