Sign inGet Started
Get started
Guides
API Reference
SDKs
CLI
Knowledge Base
Changelog

Get the competitor watchlist with its latest figures

GET
/v1/email/competitive/watchlist
// Requires Insights preview access for the organization.
const report = await bird.email.competitive.watchlist.get({ range: 30 });
console.log(report.data);
Response200
{
  "period": {
    "days": 30,
    "from": "2026-07-13T09:00:00Z",
    "to": "2026-08-12T09:00:00Z"
  },
  "summary": {
    "share_of_volume_percent": 10.5,
    "share_of_volume_change_points": -1.2,
    "competitor_sends": 4240000,
    "competitor_sends_change_percent": 12,
    "peer_cadence_median_per_week": 4.4,
    "peer_inbox_placement_median_rate": 0.892
  },
  "data": [
    {
      "watchlist_brand_id": "cwb_01krdgeqcxet5s7t44vh8rt9mg",
      "is_workspace": false,
      "name": "Everlane",
      "industry": "DTC Apparel",
      "sending_domains": [
        "everlane.com"
      ],
      "esp": "Klaviyo",
      "list_size": 1240000,
      "panel_status": "ok",
      "sends": 1240000,
      "sends_change_percent": 18,
      "cadence_per_week": 5.2,
      "inbox_placement_rate": 0.889,
      "read_rate": 0.192,
      "audience_overlap_rate": 0.24,
      "last_campaign": {
        "id": "3914827265",
        "subject": "The Summer Sale: 40% off everything",
        "sent_at": "2026-08-09T14:02:00Z",
        "image_url": "https://images.example.com/creatives/c154c8c4-6356-40e6-92d2-7c6727ec36ca.jpg"
      },
      "provenance": {
        "sends": "panel",
        "cadence_per_week": "panel",
        "inbox_placement_rate": "panel",
        "read_rate": "panel",
        "audience_overlap_rate": "panel",
        "last_campaign": "panel"
      }
    }
  ]
}

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.

API-key calls require Insights preview access for your organization.

Query Parameters

rangeinteger

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.

Possible values: 7, 30, 90

Response Payload

period
object
required

The period every figure covers.

Show child attributes
summary
object
required

Where your sending sits against the brands you watch.

Show child attributes
summary.share_of_volume_percent
nullable number
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.

summary.share_of_volume_change_points
nullable number
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.

summary.competitor_sends
nullable integer
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.

summary.competitor_sends_change_percent
nullable number
required

Change in that volume against the period immediately before.

summary.peer_cadence_median_per_week
nullable number
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.

summary.peer_inbox_placement_median_rate
nullable number
required

Median inbox placement across the brands you watch. Your own row is excluded, as with the cadence median.

data
array of object
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.

Show child attributes

Related resources

Continue with the documentation, guides and examples for this topic.

Get an implementation brief