---
title: "Get the competitor watchlist with its latest figures"
method: GET
path: "/v1/email/competitive/watchlist"
tags: ["email-competitive"]
---

# Get the competitor watchlist with its latest figures

`GET /v1/email/competitive/watchlist`

## Request

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

Returns every competitor brand on the workspace's watchlist, plus a row for
your own sending, each with estimated send volume and how it changed against
the previous period, how often the brand sends, inbox placement, estimated
read rate, audience overlap with you, and the most recent campaign seen.

Figures about a competitor are estimates from an email panel, which observes a
sample of real inboxes and scales what it sees up to a whole audience. They
are fetched while the request runs; the panel can revise recent measurements,
so two requests minutes apart can differ. Your send volume and cadence cover
the workspace, while your panel rates and overlap use its highest-volume
sending domain. The `provenance` object records each metric's source.

Interpret `null` using each field's description: rates can be unavailable,
while a last campaign can be unobserved and overlap can be absent from the
panel response. A `0` means a measurement. `panel_status` distinguishes an
untracked domain, no observed mail and a temporarily unavailable panel.

`esp` and `list_size` are the exception, and are always `null` here. Read a
single brand to get them.

## Query parameters

- `range` 7 | 30 | 90

## Headers

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

## Response `200`

The watchlist with its figures for the requested period.

- EmailCompetitiveWatchlist: The workspace's competitor watchlist with its figures for the requested period. The list is capped by the organization's competitor limit and is returned whole, so it is not paginated. Your own row is included and is always first.
  - `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.
  - `summary` EmailCompetitiveWatchlistSummary, required: Where your sending sits against the brands you watch, over the same period as the rows. Every figure here is derived from those rows rather than measured separately, so the two always agree. As on a row, each is present and `null` when the rows cannot support it: the peer medians need at least one watched brand the panel reported on, and the share figures need sending of your own to compare.
    - `share_of_volume_percent` number, nullable, required: Your share of everything the watched set sent over the period, your own sending included in the total. Your half of the ratio is an exact count of your own sending while the rest is the panel's estimate, so the two sides are measured differently.
    - `share_of_volume_change_points` number, nullable, required: How that share moved against the period immediately before, in percentage points. A share that went from 11.7 to 10.5 reports -1.2.
    - `competitor_sends` integer, nullable, required: Estimated volume the watched brands sent between them, excluding your own sending. A panel estimate, so read it as an order of magnitude rather than a count.
    - `competitor_sends_change_percent` number, nullable, required: Change in that volume against the period immediately before.
    - `peer_cadence_median_per_week` number, nullable, required: Median campaigns per week across the brands you watch, per sending domain. Your own row is excluded, since it is the figure being held against this one.
    - `peer_inbox_placement_median_rate` number, nullable, required: Median inbox placement across the brands you watch. Your own row is excluded, as with the cadence median.
  - `data` EmailCompetitiveWatchlistRow[], required: Your own row first, then each watched brand in the order it was added. Your row is present once your workspace has sent email, since before that there is no sending of yours to compare against. Empty for a workspace that has neither sent nor added a brand.
    - `watchlist_brand_id` string
    - `is_workspace` boolean, required: True on the row describing your own workspace's sending.
    - `name` string, required: The brand's name as it was when the brand was added to the watchlist.
    - `industry` string, nullable, required: The brand's industry as it was when the brand was added, or null when the brand is not classified.
    - `sending_domains` string[], required: The domains the brand's figures describe. Always one domain today: a brand is tracked by the single one the panel sees the most of its mail from, so a brand that splits its mail across several domains reports less than its full volume. On your own row this domain scopes panel measurements, while measured sends and cadence cover the workspace.
    - `esp` string, nullable, required: A sending platform observed on the domain, or null when the panel has none on record. A brand sending through more than one platform reports one of them rather than the list. This is frequently unavailable and updates monthly at best, so treat its absence as normal rather than as pending. Populated only when you read a single brand; on the watchlist it is always null.
    - `list_size` integer, nullable, required: Estimated number of addresses the brand mails, or null when the panel has no estimate. Populated only when you read a single brand; on the watchlist it is always null.
    - `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.
    - `sends` integer, nullable, required: Messages sent in the period.
    - `sends_change_percent` number, nullable, required: Change in send volume against the period immediately before this one, as a percentage. Null when the earlier period has nothing to compare against.
    - `cadence_per_week` number, nullable, required: Average campaigns sent per week over the period.
    - `inbox_placement_rate` number, nullable, required: Share of the brand's observed mail that reached an inbox rather than a spam folder.
    - `read_rate` number, nullable, required: Share of delivered mail that was read.
    - `audience_overlap_rate` number, nullable, required: Share of the panel-observed audience of your workspace's highest-volume sending domain that also receives this brand's mail. Null on your own row or when the panel returns no overlap for a competitor. An absent panel result does not establish that the audiences are disjoint.
    - `last_campaign` object, nullable, required: The most recent campaign observed for a brand in the period.
      - `id` string, required: The identifier for this campaign. Use it to fetch this one campaign on its own. It is a string, and it needs to stay one. The values are long enough that JavaScript, and any other language that stores every number as a floating point value, will round them, and a rounded identifier matches no campaign at all. Compare it and pass it back as text.
      - `subject` string, required: The subject line the panel saw on this campaign.
      - `sent_at` string, date-time, required: When the panel first saw this campaign arrive.
      - `image_url` string, uri, nullable, required: Where the panel's capture of the rendered email can be fetched, null when it captured none. Panels image only some of what they observe, so an absent creative is an ordinary outcome rather than a failed one. The image is served from the panel's own host rather than from ours, so a page embedding it has to allow that host.
    - `provenance` EmailCompetitiveWatchlistRowProvenance, required: Where each figure on the row came from, so a comparison can be labelled honestly. Every field on a competitor's row is a panel estimate. On your own row the source varies by field: what is counted directly is reported as measured, falls back to the panel for what is not, and reports `none` for a field this row never carries at all. Read rate is a panel estimate even on your own row. Comparing a measured rate against a panel estimate of the same rate is not a like for like comparison, because the two count an open differently, so both sides of the comparison come from the panel.
      - `sends` '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.
      - `cadence_per_week` '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.
      - `inbox_placement_rate` '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.
      - `read_rate` '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.
      - `audience_overlap_rate` '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.
      - `last_campaign` '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.

## 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/6dfce1179799?raw)