Keywords Report

Retrieve performance metrics for keywords.

URL

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

Header Parameters

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

Response Codes

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

Keyword performance reports return one row per keyword. Each row contains a metadata object with keyword identifiers (including campaignId, adGroupId, text, and matchType), totalMetrics aggregated over the full date range, and a granularMetrics array broken down by the selected granularity. Rows may also include an optional insights object whose bidRecommendation field surfaces a recommended bid for the keyword.

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.

See Filter for the full set of supported comparison operators.

Request Body

See AppsReportingRequest.

groupBy Dimensions

deviceClass, storefront, countryOrRegion

The following dimensions are not supported for the KEYWORD entity: ageRange, gender, countryCode, adminArea, locality.

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.

Always filter keyword reports by adGroupId or campaignId to avoid retrieving every keyword in the account.

Constraint	Detail
Filter scope	Always filter by `adGroupId` or `campaignId` to avoid retrieving all keywords across the account.