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

> Preview, track, untrack, refresh, set regions for, or delete many tracked prompts at once.

Every bulk action takes a `selection` and works through it in batches:

* `selection` is either `{ mode: "ids", ids: [promptId, ...] }` or `{ mode: "all", filters: { ... }, excludedIds: [...] }` (every prompt matching the filters, minus the excluded ids). Filters: `platform`, `competitor`, `country`, `startDate`, `endDate`, `promptBrand`, `tracking`, `intent`, `search`.
* Call `POST /v3/ai-tracker/prompts/bulk-preview` with the `selection` and an `action` first. It changes nothing and returns `eligibility`: `{ selected, eligible, skipped, byReason }`, e.g. prompts skipped because they are already tracked or still running.

| Action | Endpoint | Rows per call | Extra body |
| - | - | - | - |
| Track | `POST /v3/ai-tracker/prompts/bulk-track` | 10 | `enqueue` (false saves without running now). Uses credits |
| Untrack | `POST /v3/ai-tracker/prompts/bulk-untrack` | 50 | none; responses and topic links are kept |
| Refresh | `POST /v3/ai-tracker/prompts/bulk-refresh` | 10 | `regions` (where paused prompts run once). Uses credits |
| Set regions | `POST /v3/ai-tracker/prompts/bulk-set-regions` | 10 | `regions` (required), `enqueue`. Uses credits |
| Delete | `POST /v3/ai-tracker/prompts/bulk-delete` | 50 | none; permanent |

Each call processes one batch of eligible prompts and returns `{ success, succeeded, failed, nextCursor, eligibility, results }`. While `nextCursor` is not `null`, call again with the same `selection` and `afterId` set to `nextCursor`. `results` has one entry per prompt with `id`, `success` and `error` when it failed. Refresh and set-regions results also carry `enqueued`, plus `runUnits` or `skipped`.

For a single prompt, use [Update a Prompt](https://snowseo.com/docs/api-reference/endpoints/track-prompts-update.md), [Delete a Prompt](https://snowseo.com/docs/api-reference/endpoints/track-prompts-delete.md) or [Refresh a Prompt](https://snowseo.com/docs/api-reference/endpoints/track-prompts-refresh.md).


## OpenAPI

````yaml POST /v3/ai-tracker/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/ai-tracker/prompts/bulk-preview:
    post:
      tags:
        - AI Tracker
      summary: Count which selected prompts a bulk action applies to
      description: >-
        Read-only. For a selection of tracked prompts (explicit ids, or all
        matching the filters 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: promptsBulkPreview
      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:
                    - track
                    - untrack
                    - refresh
                    - set-regions
                    - delete
                  description: The bulk action to count eligible rows for.
                enqueue:
                  type: boolean
                  description: >-
                    When false, saves the change without running the prompts
                    now. Tracked prompts are still picked up by the scheduled
                    refresh, which bills for them.
                regions:
                  type: array
                  items:
                    type: object
                    nullable: true
                    required:
                      - type
                      - country
                      - iso2
                    properties:
                      type:
                        type: string
                        enum:
                          - country
                          - state
                          - city
                      city:
                        type: string
                      state:
                        type: string
                      country:
                        type: string
                      iso2:
                        type: string
                      iso3:
                        type: string
      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.