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

# Preview a broadcast's audience size

> Resolves the audience query and returns how many subscribers currently match, without creating or sending anything. Intended for confirming a broadcast's blast radius before triggering it.



## OpenAPI

````yaml /openapi.json post /workflows/{workflowId}/broadcast/preview
openapi: 3.1.0
info:
  title: subscriber.dev API
  description: >-
    Trigger workflows, manage subscribers and send broadcasts. Authenticate with
    an API key in the X-API-Key header: the key decides the environment. Docs:
    https://docs.subscriber.dev
  version: '1.0'
  contact: {}
servers:
  - url: https://api.subscriber.dev
    description: Cloud
security: []
tags: []
paths:
  /workflows/{workflowId}/broadcast/preview:
    post:
      tags:
        - Broadcasts
      summary: Preview a broadcast's audience size
      description: >-
        Resolves the audience query and returns how many subscribers currently
        match, without creating or sending anything. Intended for confirming a
        broadcast's blast radius before triggering it.
      operationId: previewBroadcast
      parameters:
        - name: workflowId
          required: true
          in: path
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/TriggerBroadcastRequest'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PreviewBroadcastResponse'
        '400':
          description: Workflow is paused or has no steps
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Missing or invalid API key
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Workflow not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          description: Rate limited. Wait a second and retry.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - bearer: []
        - api-key:
            - broadcasts:read
components:
  schemas:
    TriggerBroadcastRequest:
      type: object
      properties:
        audience:
          $ref: '#/components/schemas/AudienceCondition'
        sendOverHours:
          description: >-
            Spread sends evenly over this many hours (max 168) instead of
            sending as fast as possible. Gentler on sender reputation for large
            audiences, and leaves time to pause or cancel.
          type: number
          exclusiveMinimum: 0
          maximum: 168
        allowOverPlan:
          description: >-
            subscriber.dev cloud: confirm sending to more subscribers than the
            plan includes, which moves the workspace up one plan after 3 days.
            Without it, such a broadcast is refused with an explanation; ask the
            user before setting it.
          type: boolean
      required:
        - audience
    PreviewBroadcastResponse:
      type: object
      properties:
        matchedCount:
          type: number
      required:
        - matchedCount
    ErrorResponse:
      type: object
      properties:
        statusCode:
          type: integer
          example: 404
        message:
          type: string
          example: Workflow not found
        error:
          type: string
          example: Not Found
        errors:
          description: Which fields failed validation, on a 400.
          type: array
          items:
            type: object
            properties:
              path:
                type: array
                items:
                  anyOf:
                    - type: string
                    - type: number
              message:
                type: string
              code:
                type: string
            required:
              - path
              - message
      required:
        - statusCode
        - message
    AudienceCondition:
      anyOf:
        - $ref: '#/components/schemas/OptedInCondition'
        - $ref: '#/components/schemas/TagCondition'
        - $ref: '#/components/schemas/AttributeCondition'
        - $ref: '#/components/schemas/AndCondition'
        - $ref: '#/components/schemas/OrCondition'
        - $ref: '#/components/schemas/NotCondition'
    OptedInCondition:
      type: object
      properties:
        type:
          type: string
          const: optedIn
      required:
        - type
    TagCondition:
      type: object
      properties:
        type:
          type: string
          const: tag
        tag:
          type: string
          minLength: 1
      required:
        - type
        - tag
    AttributeCondition:
      type: object
      properties:
        type:
          type: string
          const: attribute
        field:
          type: string
          minLength: 1
        op:
          type: string
          enum:
            - equals
            - contains
            - exists
        value:
          type: string
      required:
        - type
        - field
        - op
    AndCondition:
      type: object
      properties:
        type:
          type: string
          const: and
        clauses:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/AudienceCondition'
      required:
        - type
        - clauses
    OrCondition:
      type: object
      properties:
        type:
          type: string
          const: or
        clauses:
          minItems: 1
          type: array
          items:
            $ref: '#/components/schemas/AudienceCondition'
      required:
        - type
        - clauses
    NotCondition:
      type: object
      properties:
        type:
          type: string
          const: not
        clause:
          $ref: '#/components/schemas/AudienceCondition'
      required:
        - type
        - clause
  securitySchemes:
    bearer:
      scheme: bearer
      type: http
      description: >-
        A session token from `subscriber login`, used by subscriber.dev's own
        apps. Requests about an environment also need its ID in the
        `x-environment-id` header. From your own code, use an API key.
    api-key:
      type: apiKey
      in: header
      name: X-API-Key
      description: An environment API key. Keep it on your server.

````

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