Keywords Report
Retrieve performance metrics for keywords.
URL
POST https://api.ads.apple.com/v1/reports/apps/keywords/queryHeader 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 ( |
| 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.
Filter by the required campaignId in the filters array, optionally narrowed further by adGroupId. 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, countryOrRegion
The following dimensions are not supported for the KEYWORD entity: ageRange, gender, countryCode, adminArea, locality.
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 |
|---|---|
| Date range must span 90 days or less. |
| Date range must span 7 days or less, and the start date must be within the last 365 days. |
| Date range must span at least 14 days. |
| 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.
Always filter keyword reports by the required campaignId, optionally narrowed further by adGroupId.
Constraint | Detail |
|---|---|
Filter by | Required to scope results and avoid retrieving all keywords across the account. |