Sign in

List Google Ads search terms

<Info>This API is in beta. Endpoints, fields, and behavior may still change, so avoid depending on it in production.</Info>

Returns the search terms that triggered the account's ads, ordered by impressions.

Pass either date_range or both start_date and end_date. Sending only one of the two dates is rejected with a 400, as is a start_date after end_date. Explicit dates win over date_range.

date_range accepts TODAY, YESTERDAY, LAST_7_DAYS, LAST_14_DAYS, LAST_30_DAYS, LAST_90_DAYS, THIS_WEEK_MON_TODAY, THIS_WEEK_SUN_TODAY, LAST_WEEK_MON_SUN, LAST_WEEK_SUN_SAT, LAST_BUSINESS_WEEK, THIS_MONTH, and LAST_MONTH, and defaults to LAST_30_DAYS. LAST_7_DAYS, LAST_30_DAYS and LAST_90_DAYS count back from today in the account's own time zone and include today; the other values are Google Ads' windows, which end yesterday.

At most 100 terms come back and there is no paging, so a busy account returns only its top 100. Terms are gathered from every campaign type on the account and merged into one list. When one of those reads fails the rest are still returned, under a 200 and with nothing in the response to say some terms are missing.

<Note>This endpoint accepts a personal API key. Workspace API keys are not authorized for it and are rejected with a 403.</Note>

get/api/apps/{app_id}/google-ads/analytics/search-terms

Path parameters

app_idstring required

ID of the app whose Google Ads reporting you want to read.

ID of the app whose Google Ads reporting you want to read.

Query parameters

date_rangestring

A preset window, for example LAST_7_DAYS or LAST_MONTH. Ignored when start_date and end_date are both set.

A preset window, for example LAST_7_DAYS or LAST_MONTH. Ignored when start_date and end_date are both set.

start_datestring nullable

First day of an explicit window, as YYYY-MM-DD. Requires end_date.

First day of an explicit window, as YYYY-MM-DD. Requires end_date.

end_datestring nullable

Last day of an explicit window, as YYYY-MM-DD. Requires start_date.

Last day of an explicit window, as YYYY-MM-DD. Requires start_date.

Response

Up to 100 search terms, highest impressions first.

search_termstring required

The term the user searched for.

campaignstring required

Name of the campaign whose ad the term matched.

impressionsinteger required

Impressions the term drove in the window.

clicksinteger required

Clicks the term drove in the window.

cost_microsinteger required

Amount spent on the term in the window, in micros of the account's currency.

conversionsnumber required

Conversions attributed to the term in the window.

Example response

[
  {
    "search_term": "oak dining table",
    "campaign": "Spring sale - Search",
    "impressions": 980,
    "clicks": 17,
    "cost_micros": 24500000,
    "conversions": 2
  }
]

Changes

Changed in 2 of the 11 revisions of this API.2