---
title: "Get historical keyword metrics"
method: POST
path: "/v1/ads/keywords/historical-metrics"
tags: ["Ad Insights"]
---

# Get historical keyword metrics

`POST /v1/ads/keywords/historical-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.

## Request body

- object
  - `accountId` string, required — Zernio googleads SocialAccount id.
  - `adAccountId` string — Platform ad account ID (Google customer ID, digits only).
  - `customerId` string — Alias of adAccountId, kept for existing callers
  - `keywords` string[], required
  - `countries` string[] — ISO 3166-1 alpha-2 country codes. Omitted = worldwide.
  - `languageConstantId` string — Google languageConstant id (1000 = English).
  - `network` 'GOOGLE_SEARCH' | 'GOOGLE_SEARCH_AND_PARTNERS'
  - `includeAdultKeywords` boolean
  - `includeAverageCpc` boolean — Adds averageCpcMicros to each row's keywordMetrics.

## Response `200`

Historical metric rows (raw Keyword Planner shape)

- object
  - `customerId` string — The customer the request ran against.
  - `data` object[]
  - `aggregateMetricResults` object, nullable

## Other responses

- `400` — Invalid input, or Google rejected the request; the message carries Google's error
- `401` — Unauthorized
- `404` — The account or requested resource was not found or is not accessible. An account ID may have been disconnected and removed. Read GET /v1/accounts for current account IDs.
- `409` — The account exists but is inactive or needs reconnection. Reconnect it, then read GET /v1/accounts for its current account ID before retrying. Code: ads_connection_required.
- `429` — Per-user Google Ads operations budget or the shared Google quota reached; the message says which and when it resets.
- `501` — Only supported on Google Ads

## Changes

- **2026-09-23** `dd3865482f9f` — 2 info
  - added the new optional request property `adAccountId`
  - request property `customerId` deprecated
- **2026-09-16** `3e6ddf2a99ea` — 2 info
  - added the optional property `details/budgetScope` to the response with the `404` status
  - added the optional property `details/budgetScope` to the response with the `409` status
- **2026-09-15** `0dba7d004d75` — 4 info
  - added the optional property `details/quotaExhausted` to the response with the `404` status
  - added the optional property `details/quotaExhausted` to the response with the `409` status
  - added the optional property `details/quotaScope` to the response with the `404` status
  - added the optional property `details/quotaScope` to the response with the `409` status
- **2026-09-10** `e70ed06e7150` — 2 info
  - added the non-success response with the status `404`
  - added the non-success response with the status `409`

[Change history](https://skmtc.dev/zernio/apis/zernio-api/changes/v1/ads/keywords/historical-metrics/post.md)

---

[API](https://skmtc.dev/zernio/apis/zernio-api.md) · [All operations](https://skmtc.dev/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc.dev/zernio/apis/zernio-api/revisions/dd3865482f9f?raw)