Sign inGet Started

Get a watched brand's figures

GET
/v1/email/competitive/watchlist/brands/{watchlist_brand_id}
// Requires Insights preview access for the organization.
const watchlist = await bird.email.competitive.watchlist.get({ range: 30 });
const entry = watchlist.data.find((row) => row.name === "Everlane" && row.watchlist_brand_id);
if (!entry?.watchlist_brand_id) throw new Error("Add Everlane to the watchlist first");
const watchlistBrandId = entry.watchlist_brand_id;
const report = await bird.email.competitive.watchlist.brands.get(watchlistBrandId, { range: 30 });
console.log(report);
Response200
{
  "period": {
    "days": 30,
    "from": "2026-07-13T09:00:00Z",
    "to": "2026-08-12T09:00:00Z"
  },
  "brand": {
    "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"
    }
  },
  "providers": [
    {
      "mailbox_provider": "gmail",
      "inbox_rate": 0.862,
      "spam_rate": 0.091,
      "workspace_inbox_rate": 0.921
    }
  ]
}

Returns one watched brand's figures for the period, together with how each mailbox provider treated its mail and how that compares with your own.

The headline figures are the ones the watchlist reports for this brand, derived the same way from the same fields. Estimated volume can differ very slightly between the two views, because each request asks the panel about a different set of domains and the panel scales its estimate per request. The figures the two views share are either rates or built from raw counts, and are identical. The per-provider breakdown, esp, and list_size are available only here.

Every figure is an estimate from an email panel, fetched while the request runs, except your own inbox rate where noted.

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

Parameters

watchlist_brand_idstring

The watchlist entry to act on.

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
brand
object
required

The figures the watchlist reports for this brand, derived the same way. Estimated volume can differ very slightly between the two views, because each request asks the panel about a different set of domains and the panel scales its estimate per request.

esp and list_size are populated here; the watchlist reports both as null.

Show child attributes
providers
array of object
required

Placement per mailbox provider, in the order the panel returned them. Empty when the panel published no breakdown for the brand's domains.

Show child attributes

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