List Ad Search Terms
GET/api/advertising/search-terms
Customer search terms that triggered your ads, aggregated over the window per ad account, campaign, ad group and term. Use it to find terms to harvest as keywords or add as negatives. Only platforms that report search terms contribute rows.
advertising:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Requires the advertising.view permission. Token scope: advertising:read (personal access and OAuth tokens).
Filters (all optional): platform, ad_account_ids, campaign_ids, date_from / date_to (as for List Ad Performance; product_ids is accepted but does not filter search terms); search (substring of the term, max 255); min_clicks (integer, at least this many clicks); min_spend (number, at least this much spend); has_orders (true: only terms with orders, false: only terms with none).
Sorting: sort one of spend (default), orders, acos, clicks, attributed_sales; direction asc or desc (default). Terms with no ACoS sort last when sorting by acos.
Pagination: per_page default 10, max 500; page.
Fields: search_term, search_term_hash, ad_account_id, ad_account_name, platform, ad_campaign_id, campaign_name, ad_group_id, ad_group_name, impressions, clicks, spend (tenant currency), spend_account_currency (the same spend in the ad account's currency, the basis for bids), account_currency (that currency's ISO code), attributed_sales (tenant currency), orders, acos (spend / attributed sales, both in tenant currency), cvr (orders / clicks, null with no clicks), provisional.
Platforms: platforms filters by one or more platforms (comma-separated or platforms[]=); the older single platform is still accepted and merged into the list. Omit both for every platform. Additive totals (spend, sales, clicks, contribution after ads) for several platforms equal the sum of the single-platform results.
Request
Responses
- 200
- 401
- 403
- 422
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden
Response Headers
Unprocessable Entity
Response Headers
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.