---
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, reserves nothing, checks the AI-credit balance covers the whole run, then queues it. Poll /suggest-groups/job-status with the returned jobId 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
  - `jobId` string
  - `totalChunks` number

## Other responses

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

---

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