---
title: "Get send volume over time for watched brands"
method: GET
path: "/v1/email/competitive/volume-series"
tags: ["email-competitive"]
---

# Get send volume over time for watched brands

`GET /v1/email/competitive/volume-series`

## Request

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

Returns daily send volume for the watched brands you name, plus a line for your
own sending, over one shared axis. Intended for a chart comparing a handful of
competitors against yourself rather than the whole watchlist: each brand you name
and each month of range adds to how long the request takes, so ask for the few
you are plotting.

Competitor volume is an estimate from an email panel, fetched while the request
runs. Your own line counts messages accepted for delivery. The `source` field on each line records which of the two it is, and
the two are not measuring the same thing, so a chart putting them on one axis
should say so.

Every line carries one point per day of the period, oldest first, with a `0` for
a day nothing was observed, so the lines need no aligning before plotting. The last
point is the last whole UTC day, not the one in progress, so your own line and a
competitor's cover the same days. A line with no points at all has a `panel_status`
saying why.

## Query parameters

- `range` 7 | 30 | 90
- `brand_ids` CompetitiveWatchlistBrandID[]

## Headers

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

## Response `200`

The requested lines for the period.

- EmailCompetitiveVolumeSeries: Volume over time for the requested watched brands, plus your own sending, on one shared daily axis.
  - `period` EmailCompetitivePeriod, required: The period the response describes. Most reports resolve a rolling window when requested; send-time and notable reports can carry the panel's own window. These bounds describe coverage, not a guarantee of measurement freshness.
    - `days` integer, required: Length of the period in days.
    - `from` string, date-time, required: Start of the period, inclusive.
    - `to` string, date-time, required: End of the period, exclusive. Daily figures therefore run through the previous whole UTC day and never include the one in progress.
  - `data` EmailCompetitiveBrandSeries[], required: Your own line first, then the requested brands in the order they were asked for. Your line is present once your workspace has sent email. Every line carries the same days in the same order, so they can be plotted against one axis without aligning them first.
    - `watchlist_brand_id` string
    - `is_workspace` boolean, required: True on the line describing your own workspace's sending.
    - `name` string, required: Label for the line: the brand's name, or your sending domain on your own line.
    - `sending_domains` string[], required: The sending domains the line's figures describe. Always one domain today.
    - `panel_status` 'ok' | 'not_in_panel' | 'no_data' | 'unavailable', required: Whether panel figures are available for a row, and when they are not, why. `ok` means the panel reported figures for the requested period. `not_in_panel` means the panel does not track the sending domain at all, which is common for smaller and newer senders. `no_data` means the panel tracks the domain but observed no mail from it in the period. `unavailable` means the figures could not be retrieved this time and the same request may well succeed on a retry.
    - `source` 'measured' | 'panel' | 'none', required: Where a figure came from. `measured` means it is counted from your own sending. `panel` means it is an estimate from an email panel, which observes a sample of real inboxes and scales what it sees up to a whole audience. `none` means there is no figure for this field on this row, so there is nothing to attribute a source to. Only your own row carries `measured` figures, and only where the metric is counted rather than estimated. Everything about a competitor is a panel estimate.
    - `points` EmailCompetitiveVolumePoint[], required: One point per day of the period, oldest first, ending with the last whole UTC day rather than the one in progress. A domain the panel tracks but observed nothing for plots as zeros, which is a measured silence rather than a missing measurement. Points are empty only when there was nothing to plot at all, reported by `panel_status` as `not_in_panel` or `unavailable`.
      - `date` string, date, required: The UTC day this point covers.
      - `sends` integer, required: Volume for the day. An estimate for a competitor and an exact count for your own line; `source` on the series records which. A day nothing was observed is `0` rather than a missing point, so every line shares one axis.

## 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
- `503`: The service is temporarily unavailable. If `Retry-After` is present, wait for that delay before retrying; otherwise, retry with exponential backoff. Reuse the same idempotency key and request when retrying a mutation.

---

[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/3e2a50466454?raw)