> ## 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 topic prompt actions

> Preview, track, untrack, remove, or move many prompts of a topic cluster at once.

Every bulk action works on the prompts of one topic cluster (`topicId`, required) and takes a `selection`:

* `selection` is either `{ mode: "ids", ids: [promptId, ...] }` or `{ mode: "all", filters: { search?, category? }, excludedIds: [...] }`. `category` is `All` or `Mentioned`; pass `startDate` and `endDate` to set the metrics window those filters read.
* Call `POST /v3/topic-clusters/topic-prompts/bulk-preview` with the `selection`, `topicId` and an `action` first. It changes nothing and returns `eligibility`: `{ selected, eligible, skipped, byReason }`. For `move`, also pass `targetTopicId`.

| Action | Endpoint | Rows per call | Extra body |
| - | - | - | - |
| Track | `POST /v3/topic-clusters/topic-prompts/bulk-track` | 10 | none; queues first runs, which use AI credits |
| Untrack | `POST /v3/topic-clusters/topic-prompts/bulk-untrack` | 50 | none |
| Remove | `POST /v3/topic-clusters/topic-prompts/bulk-remove` | 50 | none; unlinks the prompt and its regional variants, the prompts stay |
| Move | `POST /v3/topic-clusters/topic-prompts/bulk-move` | 50 | `targetTopicId` (required) |

A move is skipped for every row, and nothing moves, while any selected prompt is already in the target or no longer in the source.

Each call processes one batch and 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` and `error` when it failed.

For a single prompt, use [Topic Prompts](https://snowseo.com/docs/api-reference/endpoints/topic-prompts.md) to add or `DELETE /v3/topic-clusters/{topicId}/prompts/{promptId}` to remove.


## OpenAPI

````yaml POST /v3/topic-clusters/topic-prompts/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/topic-prompts/bulk-preview:
    post:
      tags:
        - Topic Clusters
      summary: Count which selected topic prompts a bulk action applies to
      description: >-
        Read-only. For a selection of a topic cluster's prompts (explicit ids,
        or all matching a search or category minus exclusions), reports how many
        the given bulk action would change and why the rest would be skipped.
        Call it before a bulk action and confirm the counts with the user.
      operationId: topicPromptsBulkPreview
      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
                          properties:
                            search:
                              type: string
                            category:
                              type: string
                              enum:
                                - All
                                - Ranked
                                - Mentioned
                        excludedIds:
                          type: array
                          items:
                            type: string
                action:
                  type: string
                  enum:
                    - track
                    - untrack
                    - remove
                    - move
                  description: The bulk action to count eligible rows for.
                topicId:
                  type: string
                  description: Topic cluster the rows belong to.
                startDate:
                  type: string
                  description: >-
                    Start of the metrics window the selection filters read
                    (YYYY-MM-DD).
                endDate:
                  type: string
                  description: >-
                    End of the metrics window the selection filters read
                    (YYYY-MM-DD).
                targetTopicId:
                  type: string
                  format: uuid
                  description: Topic cluster to move the rows into.
      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.