---
title: "Count which selected prompts can join a topic cluster"
method: POST
path: "/v3/topic-clusters/prompt-assignments/bulk-preview"
tags: ["Topic Clusters"]
---

# Count which selected prompts can join a topic cluster

`POST /v3/topic-clusters/prompt-assignments/bulk-preview`

## Request

- Base URL: `https://api.snowseo.com`
- URL: `https://api.snowseo.com/v3/topic-clusters/prompt-assignments/bulk-preview`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`
- TypeScript: <https://skmtc.dev/snowseo/apis/snowseo-api/docs/v3/topic-clusters/prompt-assignments/bulk-preview/post.ts> (a function with typed inputs; its response is checked against the schema)

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.

## Request body

- object
  - `teamId` string
  - `selection` union, required
    - object
      - `mode` 'ids', required
      - `ids` string[], required
    - object
      - `mode` 'all', required
      - `filters` object, required
        - `platform` string
        - `competitor` string
        - `country` string
        - `startDate` string
        - `endDate` string
        - `promptBrand` string
        - `tracking` string
        - `intent` string
        - `search` string
      - `excludedIds` string[], required
  - `action` 'assign', required: The bulk action to count eligible rows for.
  - `topicId` string: Topic cluster ID.
  - `track` boolean: Also enable tracking on the newly linked prompts.

## Response `200`

Default Response

- object
  - `eligibility` object
    - `selected` number, required
    - `eligible` number, required
    - `skipped` number, required
    - `byReason` object, required

## Other responses

- `500`: Default Response

## Changes

- **2026-11-03** `31b321592ad7`: 4 info
  - added the optional property `code` to the response with the `500` status
  - added the optional property `message` to the response with the `500` status
  - added the optional property `reference` to the response with the `500` status
  - added the optional property `success` to the response with the `500` status
- **2026-11-01** `6d1dc4928d97`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/snowseo/apis/snowseo-api/changes/v3/topic-clusters/prompt-assignments/bulk-preview/post.md)

---

[API](https://skmtc.dev/snowseo/apis/snowseo-api.md) - [All operations](https://skmtc.dev/snowseo/apis/snowseo-api/llms.txt) - [OpenAPI document](https://skmtc.dev/snowseo/apis/snowseo-api/revisions/f64935aae2ec?raw)