email-competitive

Get send volume over time for watched brands

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.

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

Query parameters

range7 | 30 | 90
Example:30

How many days back the response covers, counting from now. One of three fixed trend windows rather than an open date range, matching how a competitive-intelligence chart is read. Defaults to 30.

brand_idsCompetitiveWatchlistBrandID[]

Which watched brands to plot, in the order you want the lines. Omit to get only your own line. An id your workspace does not watch is rejected rather than skipped, so a chart cannot quietly lose a line.

[
  "cwb_01krdgeqcxet5s7t44vh8rt9mg"
]

Headers

X-Workspace-Idstring

Workspace context for the request. Required for dashboard authentication and master keys. Workspace keys and access tokens already identify their workspace; send that workspace or omit the header. A different one is rejected.

X-Organization-Idstring

Organization context for the request. Required for dashboard authentication. An API key or access token carries its own organization, so send either that organization or no header at all; a different one is rejected.

Response

The requested lines for the period.

Example response

{
  "period": {
    "days": 30,
    "from": "2026-07-13T09:00:00Z",
    "to": "2026-08-12T09:00:00Z"
  },
  "data": [
    {
      "watchlist_brand_id": "cwb_01krdgeqcxet5s7t44vh8rt9mg",
      "name": "Everlane",
      "sending_domains": [
        "everlane.com"
      ],
      "panel_status": "ok",
      "source": "panel",
      "points": [
        {
          "date": "2026-08-09",
          "sends": 41800
        }
      ]
    }
  ]
}

Changes

No recorded changes to this operation across all 2 revisions of this API.