Search Terms Report

Retrieve performance metrics for the actual search terms that triggered keyword matches.

URL

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

Header Parameters

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

Response Codes

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

Search term reports show the actual user-entered queries that matched a keyword and generated an impression. Each row contains the searchTermText field and the associated keyword object, allowing you to map observed search behavior back to specific bid keywords.

Use search term data to:

Discover high-performing search terms to promote to dedicated exact-match keywords.
Identify irrelevant queries to exclude as negative keywords with Create a Negative Keyword.
Understand match expansion breadth for BROAD-match keywords.

Every apps report request requires a campaignId filter; optionally add adGroupId in the filters array to scope results further.

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 SEARCHTERM entity: ageRange, gender, countryCode, adminArea, locality.

Search term reports follow the usual granularity rules, except HOURLY isn’t available for this entity.

Granularity	Constraint
`DAILY`	Date range start must be within the last 90 days. Date range must be greater than one day.
`HOURLY`	Not supported for the `SEARCHTERM` entity.
`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.

Search term reporting has several additional restrictions, including a required ORTZ timezone and privacy-based suppression of low-volume terms.

Constraint	Detail
`EMPTY_METRICS` option	Not supported for `SEARCHTERM`.
Timezone	Only `ORTZ` is supported. `UTC` is excluded for search term reporting.
HOURLY granularity	Not available for search terms.
Privacy threshold	Low-volume search terms may be suppressed or aggregated to protect user privacy.