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);
Odpowiedź200
{
  "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.

Parametry

watchlist_brand_idstring

The watchlist entry to act on.

Parametry zapytania

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

Treść odpowiedzi

period
object
wymagane

The period every figure covers.

Pokaż atrybuty podrzędne
period.days
integer
wymagane

Length of the period in days.

period.from
string
wymagane

Start of the period, inclusive.

period.to
string
wymagane

End of the period, exclusive. Daily figures therefore run through the previous whole UTC day and never include the one in progress.

brand
object
wymagane

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.

Pokaż atrybuty podrzędne
providers
array of object
wymagane

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

Pokaż atrybuty podrzędne

Przejdź do dokumentacji, przewodników i przykładów dotyczących tego tematu.