Skip to main content
POST
Count which selected prompts can join a topic cluster
Assigns tracked prompts to a topic cluster. The selection is the one the tracked prompts table uses: { mode: "ids", ids: [...] }, or { mode: "all", filters: { platform?, competitor?, country?, startDate?, endDate?, promptBrand?, tracking?, intent?, search? }, excludedIds: [...] }.
  • Call POST /v3/topic-clusters/prompt-assignments/bulk-preview with the selection, action: "assign" and topicId first. It changes nothing and returns eligibility: { selected, eligible, skipped, byReason }. Prompts already in a topic are skipped as already-in-topic, or already-in-target when they are in topicId.
  • POST /v3/topic-clusters/prompt-assignments/bulk-assign links the eligible prompts, with their regional variants, to topicId (required). Set track: true to also turn tracking on, which uses credits. It processes 10 prompts per call.
Each call returns { success, succeeded, failed, nextCursor, eligibility, results }. While nextCursor is not null, call again with the same body and afterId set to nextCursor. results has one entry per prompt with id, prompt, success, promptIds (the linked prompt ids), promptsSkipped (left untracked for lack of credits) and error when it failed. To add prompts by text, or to create new ones, use Topic Prompts.

Authorizations

Authorization
string
header
required

Your SnowSEO API key (sk_...).

Body

application/json
selection
object
required
action
enum<string>
required

The bulk action to count eligible rows for.

Available options:
assign
teamId
string
topicId
string

Topic cluster ID.

track
boolean

Also enable tracking on the newly linked prompts.

Response

Default Response

eligibility
object