---
title: "Generate keyword ideas"
method: POST
path: "/v1/ads/keywords/ideas"
tags: ["Ad Insights"]
---

# Generate keyword ideas

`POST /v1/ads/keywords/ideas`

Google Ads only. Runs Keyword Planner's generateKeywordIdeas from seed keywords, a seed URL,
or both, returning idea rows verbatim (avgMonthlySearches, competition, competitionIndex,
top-of-page bid micros, monthlySearchVolumes). Counters are int64s encoded as strings; bid
values are micros of the account currency. Omitting `countries` targets worldwide.

## 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.
  - `seedKeywords` string[] — Seed terms. Provide these, seedUrl, or both.
  - `seedUrl` string, uri — Landing page to mine for ideas. Provide this, seedKeywords, or both.
  - `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
  - `pageSize` integer
  - `pageToken` string — Cursor from paging.nextPageToken of the previous page.

## Response `200`

Keyword idea rows (raw Keyword Planner shape)

- object
  - `customerId` string — The customer the request ran against.
  - `data` object[]
  - `aggregateMetricResults` object, nullable
  - `paging` object
    - `nextPageToken` string, nullable — Cursor for the next page; null when exhausted.

## 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-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/ideas/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/be448f13ecdc?raw)