Skip to main content

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.

Required scope: advertising:read

Grant 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​

OK

Response Headers
    Content-Type