---
title: "Queue an AI keyword grouping run"
method: POST
path: "/v3/topic-clusters/suggest-groups/start"
tags: ["Topic Clusters"]
---

# Queue an AI keyword grouping run

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

Validates the keywords, checks the AI-credit balance, then queues the run. Poll /suggest-groups/status with the returned runId for progress and the grouped result. Costs 1 AI credit per 100 unique keywords; question matching is free.

## 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
  - `source` 'gsc-auto-create' | 'smart-group', nullable

## Response `200`

Default Response

- object
  - `runId` string
  - `totalChunks` number

## Other responses

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

## Changes

- **2026-09-26** `68d7cda28432` — 1 warning, 1 info
  - removed the optional property `jobId` from the response with the `200` status
  - added the optional property `runId` to the response with the `200` status
- **2026-08-15** `f69a1d263036` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/snowseo/apis/snowseo-api/changes/v3/topic-clusters/suggest-groups/start/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.dev/snowseo/apis/snowseo-api/revisions/68d7cda28432?raw)