---
title: "Add keyword to topic cluster"
method: POST
path: "/v3/topic-clusters/{topicId}/keywords"
tags: ["Topic Clusters"]
---

# Add keyword to topic cluster

`POST /v3/topic-clusters/{topicId}/keywords`

Links a keyword to a topic cluster, optionally tracking it for rank monitoring.

## Path parameters

- `topicId` string, required

## Request body

- object
  - `teamId` string — Team ID
  - `keyword` string — Keyword text to add
  - `countryId` string, nullable
  - `languageId` string, nullable
  - `locationCriteriaId` number, nullable — Google Ads location criteria ID for city/region-level tracking. Omit/null for country-only.
  - `locationCanonicalName` string, nullable — Canonical location name paired with locationCriteriaId.
  - `items` object[] — Bulk mode: one item per keyword. Items already linked to another topic are skipped.
    - `keyword` string, required
    - `countryId` string, nullable
    - `languageId` string, nullable
    - `locationCriteriaId` number, nullable
    - `locationCanonicalName` string, nullable
  - `track` boolean — Whether to also track this keyword for rank monitoring

## Response `200`

Default Response

- object
  - `success` boolean
  - `keywordId` string
  - `countryId` string, nullable
  - `languageId` string, nullable
  - `locationCriteriaId` number, nullable
  - `locationCanonicalName` string, nullable
  - `requested` number
  - `added` number
  - `alreadyHere` number
  - `skipped` number

## Other responses

- `400` — Default Response
- `404` — Default Response
- `409` — Default Response
- `500` — 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/versions/aa8eaa9e34a0/schema)