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);
Antwort200
{
  "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.

Parameter

watchlist_brand_idstring

The watchlist entry to act on.

Abfrageparameter

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

Antwort-Payload

period
object
erforderlich

The period every figure covers.

Untergeordnete Attribute anzeigen
brand
object
erforderlich

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.

Untergeordnete Attribute anzeigen
brand.watchlist_brand_id
string

The watchlist entry, for removing the brand. Absent on your own row, which is not a watchlist entry.

brand.is_workspace
boolean
erforderlich

True on the row describing your own workspace's sending.

brand.name
string
erforderlich

The brand's name as it was when the brand was added to the watchlist.

brand.industry
nullable string
erforderlich

The brand's industry as it was when the brand was added, or null when the brand is not classified.

brand.sending_domains
array of string
erforderlich

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.

brand.esp
nullable string
erforderlich

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.

brand.list_size
nullable integer
erforderlich

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.

brand.panel_status
string
erforderlich

Whether panel figures were available for this row, and when they were not, why.

Possible values: ok, not_in_panel, no_data, unavailable

brand.sends
nullable integer
erforderlich

Messages sent in the period.

brand.sends_change_percent
nullable number
erforderlich

Change in send volume against the period immediately before this one, as a percentage. Null when the earlier period has nothing to compare against.

brand.cadence_per_week
nullable number
erforderlich

Average campaigns sent per week over the period.

brand.inbox_placement_rate
nullable number
erforderlich

Share of the brand's observed mail that reached an inbox rather than a spam folder.

brand.read_rate
nullable number
erforderlich

Share of delivered mail that was read.

brand.audience_overlap_rate
nullable number
erforderlich

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.

brand.last_campaign
nullable object
erforderlich

The most recent campaign observed in the period, or null when none was. Always null on your own row.

Untergeordnete Attribute anzeigen
brand.provenance
object
erforderlich

Where each figure on this row came from.

Untergeordnete Attribute anzeigen
providers
array of object
erforderlich

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

Untergeordnete Attribute anzeigen

Weiter mit der Dokumentation, Anleitungen und Beispielen zu diesem Thema.