---
title: "Export broadcasts as CSV"
method: GET
path: "/v1/email/broadcasts/export"
tags: ["email-broadcasts"]
---

# Export broadcasts as CSV

`GET /v1/email/broadcasts/export`

## Request

- Base URL: `https://us1.platform.bird.com`
- URL: `https://us1.platform.bird.com/v1/email/broadcasts/export`
- Auth: one of:
  - HTTP bearer
  - API key in cookie `bird_session`

Downloads the workspace's broadcasts as a CSV file, one row per broadcast,
newest first. The header names fifteen columns, in this order:
`created_at`, `broadcast_id`, `status`, `template_name`, `audience_id`,
`audience_name`, `recipient_count`, `sent_count`, `delivered_count`,
`track_opens`, `open_rate`, `track_clicks`, `click_rate`, `scheduled_at`
and `sent_at`. `broadcast_id` is what joins a row back to the rest of the
API. It takes the same filters as the broadcast list, so the file matches
what the list shows for the same query. `recipient_count` is empty until a
send resolves the audience, so an empty cell there means the broadcast has
no recipient list yet rather than a list of nobody.

`open_rate` and `click_rate` are decimal fractions to four places, over the
recipients the message reached: `open_rate` is unique non-prefetched opens
divided by that number, and `click_rate` is unique clicks divided by it.
That divisor is not the `delivered_count` column, which resolves each
recipient to a single status and so counts a recipient who delivered and
then complained under the complaint, so neither rate can be reproduced from
this file alone. Either is empty when its `track_opens` or `track_clicks`
flag is `false`, and also when the message reached nobody, so an empty rate
does not mean tracking is off. Both flags default to `true` and the export
narrows by no status of its own, so a `draft` or `scheduled` row is included
unless `status` excludes it, and carries `track_opens` as `true` with
`open_rate` empty.

A text cell whose first character is `=`, `+`, `-`, `@`, a tab or a carriage
return is written with a leading apostrophe, so a spreadsheet reads it as
text rather than as a formula. A value that begins with an apostrophe of
its own is written unchanged, so the original text cannot always be
recovered from the CSV cell. Match records by `broadcast_id` or `audience_id`,
rather than by `template_name` or `audience_name`.

The file is complete or it is refused: a query matching more broadcasts than
one file carries returns a 422 naming the limit rather than a truncated
download. Narrow it with `created_after` and `created_before` and request
each window separately.

## Query parameters

- `status` EmailBroadcastStatus[]
- `audience_id` string
- `tag` string
- `q` string
- `created_after` string, date-time
- `created_before` string, date-time

## Headers

- `X-Workspace-Id` string
- `X-Organization-Id` string

## Response `200`

The broadcasts as a CSV file.

## Other responses

- `400`: Bad request
- `401`: Authentication required
- `403`: Insufficient permissions
- `404`: Resource not found
- `422`: The request has invalid field values, violates a business rule, or carries a query parameter the endpoint does not declare. Field validation errors use `type: validation_error` and include the affected fields in `details`. Business-rule errors identify the failed rule in `type`.
- `429`: Rate limit exceeded
- `500`: Internal server error

---

[API](https://skmtc.dev/messagebird/apis/bird-api.md) · [All operations](https://skmtc.dev/messagebird/apis/bird-api/llms.txt) · [OpenAPI document](https://skmtc.dev/messagebird/apis/bird-api/revisions/6dfce1179799?raw)