Query Keywords
Query keywords using structured filters, sorting, and pagination.
URL
POST https://api.ads.apple.com/v1/keywords/queryHeader Parameters
| Name | Type | Description |
|---|---|---|
X-Ap-Context Required | string |
Response Codes
| Status | Reason | Type | Description |
|---|---|---|---|
| 200 | OK Content-Type: application/json | KeywordQueryResponse | |
| 400 | Bad Request Content-Type: application/json | ErrorResponse | |
| 401 | Unauthorized Content-Type: application/json | ErrorResponse | |
| 403 | Forbidden Content-Type: application/json | ErrorResponse | |
| 404 | Not Found Content-Type: application/json | ErrorResponse | |
| 429 | Too Many Requests Content-Type: application/json | ErrorResponse | |
| 500 | Internal Server Error Content-Type: application/json | ErrorResponse |
Discussion
This endpoint queries keywords using a standard QueryRequest body. Either adGroupId or campaignId is required. The API returns an error if neither is present.
The
adGroupId EQUALSoradGroupId INfilter scopes the query to one or more specific ad groups, and can span ad groups across different campaigns within the same ad account. TheadGroupId INfilter accepts up to 1000 values. TheIS_NULL,IS_NOT_NULL, andNOT_EQUALSoperators aren’t supported onadGroupIdfor keywords.The
campaignIdfield scopes the query to all keywords across a campaign, and only supportsEQUALS. There is no campaign-level keyword concept the way there is for negative keywords.Filtering by
id(EQUALSorIN) is exempt from theadGroupId/campaignIdrequirement, sinceidalready fully bounds the query.
See QueryFilterOperator for the full set of supported comparison operators.
Filterable Fields
Field | Type | Operators | Sortable | Description |
|---|---|---|---|---|
| integer |
| Yes (default) | The unique identifier for the keyword. |
| integer |
| Yes | The ad group this keyword belongs to. |
| integer |
| Yes | The campaign ID of the parent campaign. Informational only. |
| string |
| Yes | The original advertiser-given keyword text. |
| string (enum) |
| Yes | Keyword match type. See Keywordmatchtype. |
| string (enum) |
| Yes | Whether the keyword is active and eligible to serve. See Keywordstatus. |
| boolean |
| Yes | Whether the keyword has been deleted. |
The request body is a QueryRequest composed of QueryFilter conditions and QuerySort directives (QuerySortOrder), controlled by QueryPagination.