Sign in
Ad Insights

Get historical keyword metrics

Google Ads only. Runs Keyword Planner's generateKeywordHistoricalMetrics for up to 1,000 exact keywords: historical search volume, competition and top-of-page bid ranges, plus averageCpcMicros when includeAverageCpc is set. Rows come back verbatim; counters are int64s encoded as strings, bid/CPC values are micros of the account currency.

post/v1/ads/keywords/historical-metrics

Request body

accountIdstring required

Zernio googleads SocialAccount id.

adAccountIdstring

Platform ad account ID (Google customer ID, digits only).

customerIdstring

Alias of adAccountId, kept for existing callers

keywordsstring[] required
countriesstring[]

ISO 3166-1 alpha-2 country codes. Omitted = worldwide.

languageConstantIdstring

Google languageConstant id (1000 = English).

network'GOOGLE_SEARCH' | 'GOOGLE_SEARCH_AND_PARTNERS'
includeAdultKeywordsboolean
includeAverageCpcboolean

Adds averageCpcMicros to each row's keywordMetrics.

Response

Historical metric rows (raw Keyword Planner shape)

customerIdstring

The customer the request ran against.

dataobject[]
aggregateMetricResultsobject nullable

Changes

Changed in 5 of the 56 revisions of this API.18

  • 2c04683ce6948See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    This revision also has 2 changes that name no endpoint, such as unreferenced schemas being removed. See the revision's changelog

  • dd3865482f9f2See the full diff
    • ○

      added the new optional request property

      new-optional-request-property

    • ○

      request property deprecated

      request-property-deprecated

  • 3e6ddf2a99ea2See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • 0dba7d004d754See the full diff
    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

    • ○

      added the optional property / to the response with the status

      response-optional-property-added

  • e70ed06e71502See the full diff
    • ○

      added the non-success response with the status

      response-non-success-status-added

    • ○

      added the non-success response with the status

      response-non-success-status-added