---
title: "List broadcasts"
method: GET
path: "/api/broadcasts.list"
---

# List broadcasts

`GET /api/broadcasts.list`

Retrieves a list of broadcasts with pagination and optional filtering by status. Supports fetching template details for each variation.

## Query parameters

- `workspace_id` string, required
- `status` 'draft' | 'scheduled' | 'sending' | 'paused' | 'sent' | 'cancelled' | 'failed' | 'testing' | 'test_completed' | 'winner_selected'
- `limit` integer
- `offset` integer
- `with_templates` boolean

## Response `200`

List of broadcasts retrieved successfully

- BroadcastListResponse
  - `broadcasts` Broadcast[] — List of broadcasts
    - `id` string — Unique identifier for the broadcast
    - `workspace_id` string — The ID of the workspace
    - `name` string — Name of the broadcast
    - `channel_type` string — Communication channel type
    - `status` 'draft' | 'scheduled' | 'processing' | 'paused' | 'processed' | 'cancelled' | 'failed' | 'testing' | 'test_completed' | 'winner_selected' — Current status of the broadcast
    - `audience` AudienceSettings
      - `list` string, required — List ID to send to
      - `segments` string[] — Optional segment IDs to filter recipients
      - `exclude_unsubscribed` boolean — Whether to exclude unsubscribed contacts
    - `schedule` ScheduleSettings — Schedule settings for a broadcast. Note: When a broadcast is first created, these fields are empty/false. Use the /api/broadcasts.schedule endpoint to configure scheduling.
      - `is_scheduled` boolean — Whether the broadcast is scheduled (false after creation, set via broadcasts.schedule)
      - `scheduled_date` string — Scheduled date in YYYY-MM-DD format
      - `scheduled_time` string — Scheduled time in HH:MM format
      - `timezone` string — IANA timezone
      - `use_recipient_timezone` boolean — Send at scheduled time in each recipient's timezone
    - `test_settings` BroadcastTestSettings
      - `enabled` boolean — Whether A/B testing is enabled
      - `sample_percentage` integer — Percentage of audience to use for testing
      - `auto_send_winner` boolean — Automatically send winning variation to remaining audience
      - `auto_send_winner_metric` 'open_rate' | 'click_rate' — Metric used to determine the winner
      - `test_duration_hours` integer — Duration of the test in hours (max 7 days)
      - `variations` BroadcastVariation[] — Test variations (2-8 variations allowed)
        - `variation_name` string — Name of this variation
        - `template_id` string, required — Template ID for this variation
        - `metrics` VariationMetrics
          - `recipients` integer — Number of recipients
          - `delivered` integer — Number of delivered messages
          - `opens` integer — Number of opens
          - `clicks` integer — Number of clicks
          - `bounced` integer — Number of bounces
          - `complained` integer — Number of complaints
          - `unsubscribed` integer — Number of unsubscribes
        - `template` object, nullable — Full template object (populated when with_templates=true)
    - `utm_parameters` UTMParameters
      - `source` string — UTM source parameter
      - `medium` string — UTM medium parameter
      - `campaign` string — UTM campaign parameter
      - `term` string — UTM term parameter
      - `content` string — UTM content parameter
    - `data_feed` DataFeedSettings — Configuration for external data feeds
      - `global_feed` GlobalFeedSettings
        - `enabled` boolean — Whether the global data feed is enabled
        - `url` string — URL endpoint to fetch global data from (must be HTTPS)
        - `headers` DataFeedHeader[] — Custom HTTP headers to include in the request
          - `name` string, required — HTTP header name
          - `value` string, required — HTTP header value
      - `global_feed_data` object — Cached data from the global feed (populated after fetch)
      - `global_feed_fetched_at` string, date-time, nullable — When the global feed was last fetched
      - `recipient_feed` RecipientFeedSettings
        - `enabled` boolean — Whether the per-recipient data feed is enabled
        - `url` string — URL endpoint to fetch per-recipient data from (must be HTTPS)
        - `headers` DataFeedHeader[] — Custom HTTP headers to include in the request
          - `name` string, required — HTTP header name
          - `value` string, required — HTTP header value
    - `metadata` object — Custom metadata for the broadcast
    - `winning_template` string, nullable — ID of the winning template variation
    - `test_sent_at` string, date-time, nullable — When the A/B test was sent
    - `winner_sent_at` string, date-time, nullable — When the winning variation was sent
    - `enqueued_count` integer — Number of emails added to the queue by orchestrator
    - `test_phase_recipient_count` integer — Number of recipients in test phase
    - `winner_phase_recipient_count` integer — Number of recipients in winner phase
    - `created_at` string, date-time — When the broadcast was created
    - `updated_at` string, date-time — When the broadcast was last updated
    - `started_at` string, date-time, nullable — When the broadcast started sending
    - `completed_at` string, date-time, nullable — When the broadcast completed sending
    - `cancelled_at` string, date-time, nullable — When the broadcast was cancelled
    - `paused_at` string, date-time, nullable — When the broadcast was paused
    - `pause_reason` string, nullable — Reason for pausing the broadcast
  - `total_count` integer — Total number of broadcasts matching the query

## Other responses

- `400` — Bad request - validation failed
- `401` — Unauthorized - invalid or missing authentication token
- `500` — Internal server error

## Changes

- **2026-02-08** `b6f612d3daaa` — 1 info
  - added the optional property `broadcasts/items/data_feed` to the response with the `200` status
- **2025-12-31** `e42f05599d8a` — 2 warning, 3 info
  - added the new `processed` enum value to the `broadcasts/items/status` response property for the response status `200`
  - added the new `processing` enum value to the `broadcasts/items/status` response property for the response status `200`
  - added the optional property `broadcasts/items/enqueued_count` to the response with the `200` status
  - removed the `sending` enum value from the `broadcasts/items/status` response property for the response status `200`
  - …1 more
- **2025-11-29** `c39acad12e49` — 1 breaking, 2 warning, 1 info
  - removed the required property `broadcasts/items/audience/lists` from the response with the `200` status
  - removed the optional property `broadcasts/items/audience/skip_duplicate_emails` from the response with the `200` status
  - removed the optional property `broadcasts/items/sent_at` from the response with the `200` status
  - added the required property `broadcasts/items/audience/list` to the response with the `200` status
- …earlier changes not shown

[Full history](https://skmtc.dev/pierre-b/apis/notifuse-api/changes/api/broadcasts.list/get.md)

---

[API](https://skmtc.dev/pierre-b/apis/notifuse-api.md) · [All operations](https://skmtc.dev/pierre-b/apis/notifuse-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/pierre-b/notifuse-api/revisions/d26605f2fc47/schema)