--- title: Keywords 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-keyword-reports --- # Keywords Report Retrieve performance metrics for keywords. ## URL POST https://api.ads.apple.com/v1/reports/apps/keywords/query ## Header Parameters X-Ap-Context: ## Response Codes 200 OK: Successful response. Returns AppsKeywordReportResponse (result: AppsKeywordResultContainer). 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 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. | | | | | 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. | | Payload Examples ## See Also - [Campaigns Report](apple-ads-platform-api/get-app-campaign-reports.md) - [Ad Groups Report](apple-ads-platform-api/get-app-ad-group-reports.md) - [Ads Report](apple-ads-platform-api/get-app-ad-reports.md) - [Search Terms Report](apple-ads-platform-api/get-app-search-term-reports.md)