---
title: "Suggest keyword topic groupings"
method: POST
path: "/v3/topic-clusters/suggest-groups"
tags: ["Topic Clusters"]
---

# Suggest keyword topic groupings

`POST /v3/topic-clusters/suggest-groups`

Uses AI to split a list of keywords into topic clusters, preferring existing topics and suggesting new ones when needed. Optionally matches a list of questions (e.g. Search Console question queries) onto the resulting clusters as AI prompts. Costs 1 AI credit per 100 unique keywords; question matching is free. Returns 403 without charging when the balance cannot cover the whole run.

## Request body

- object
  - `teamId` string, required
  - `keywords` object[], required
    - `keyword` string, required
    - `countryId` string, nullable
    - `languageId` string, nullable
  - `questions` string[]
  - `targetClusterCount` number, nullable
  - `clusterMode` 'existing' | 'new' | 'mixed', nullable
  - `userIntent` string, nullable

## Response `200`

Default Response

- object
  - `groups` object[]
    - `topicId` string, nullable
    - `topicName` string
    - `isNew` boolean
    - `keywords` string[]
    - `prompts` string[]
  - `questionsConsidered` number

## Other responses

- `400` — Default Response
- `403` — Default Response
- `500` — Default Response

## Changes

- **2026-08-15** `f69a1d263036` — 2 info
  - added the non-success response with the status `403`
  - added the optional property `questionsConsidered` to the response with the `200` status
- **2026-08-13** `1d16d990e65b` — 2 info
  - added the new optional request property `questions`
  - added the optional property `groups/items/prompts` to the response with the `200` status

[Change history](https://skmtc.dev/snowseo/apis/snowseo-api/changes/v3/topic-clusters/suggest-groups/post.md)

---

[API](https://skmtc.dev/snowseo/apis/snowseo-api.md) · [All operations](https://skmtc.dev/snowseo/apis/snowseo-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/snowseo/snowseo-api/revisions/6add26eeb5ca/schema)