---
title: "Historical keyword metrics (Google Keyword Planner)"
method: POST
path: "/v1/ads/keywords/historical-metrics"
tags: ["Ad Insights"]
---

# Historical keyword metrics (Google Keyword Planner)

`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.
  - `customerId` string — Numeric Google Ads customer id (no dashes); only needed when the connection has several accounts.
  - `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 — message carries Google's error
- `401` — Unauthorized
- `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

---

[API](https://skmtc.net/zernio/apis/zernio-api.md) · [All operations](https://skmtc.net/zernio/apis/zernio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/zernio/zernio-api/revisions/d0ab3b4eb0ae/schema)