> ## Documentation Index
> Fetch the complete documentation index at: https://snowseo.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Bulk assign prompts to a topic

> Preview and assign many tracked prompts to a topic cluster at once.

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](https://snowseo.com/docs/api-reference/endpoints/topic-prompts.md).


## OpenAPI

````yaml POST /v3/topic-clusters/prompt-assignments/bulk-preview
openapi: 3.0.0
info:
  title: SnowSEO API
  description: API documentation for SnowSEO
  version: 1.0.0
servers:
  - url: https://api.snowseo.com
    description: Production server
security:
  - bearerAuth: []
  - apiKey: []
externalDocs:
  url: https://snowseo.com/docs
  description: Find more info here
paths:
  /v3/topic-clusters/prompt-assignments/bulk-preview:
    post:
      tags:
        - Topic Clusters
      summary: Count which selected prompts can join a topic cluster
      description: >-
        Read-only. For a selection of tracked prompts (explicit ids, or all
        matching the table filters minus exclusions), reports how many the
        assign action would link to the given topic and why the rest would be
        skipped. Pass topicId to tell prompts already in that topic from those
        in another. Call it before assigning and confirm the counts with the
        user.
      operationId: promptAssignmentsBulkPreview
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - selection
                - action
              properties:
                teamId:
                  type: string
                selection:
                  oneOf:
                    - type: object
                      required:
                        - mode
                        - ids
                      additionalProperties: false
                      properties:
                        mode:
                          type: string
                          enum:
                            - ids
                        ids:
                          type: array
                          items:
                            type: string
                    - type: object
                      required:
                        - mode
                        - filters
                        - excludedIds
                      additionalProperties: false
                      properties:
                        mode:
                          type: string
                          enum:
                            - all
                        filters:
                          type: object
                          additionalProperties: false
                          properties:
                            platform:
                              type: string
                            competitor:
                              type: string
                            country:
                              type: string
                            startDate:
                              type: string
                            endDate:
                              type: string
                            promptBrand:
                              type: string
                            tracking:
                              type: string
                            intent:
                              type: string
                            search:
                              type: string
                        excludedIds:
                          type: array
                          items:
                            type: string
                action:
                  type: string
                  enum:
                    - assign
                  description: The bulk action to count eligible rows for.
                topicId:
                  type: string
                  description: Topic cluster ID.
                track:
                  type: boolean
                  description: Also enable tracking on the newly linked prompts.
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  eligibility:
                    type: object
                    required:
                      - selected
                      - eligible
                      - skipped
                      - byReason
                    properties:
                      selected:
                        type: number
                      eligible:
                        type: number
                      skipped:
                        type: number
                      byReason:
                        type: object
                        additionalProperties:
                          type: number
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
                properties:
                  success:
                    type: boolean
                  error:
                    type: string
                  code:
                    type: string
                  message:
                    type: string
                  reference:
                    type: string
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: Your SnowSEO API key (sk_...).
    apiKey:
      type: apiKey
      name: x-api-key
      in: header

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.