Sign inGet Started
Rozpocznij
Przewodniki
Referencja API
SDK
CLI
Baza wiedzy
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);
Odpowiedź200
{
  "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.

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.

summary
object
wymagane

Where your sending sits against the brands you watch.

Pokaż atrybuty podrzędne
data
array of object
wymagane

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.

Pokaż atrybuty podrzędne

Powiązane zasoby

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

Uzyskaj brief wdrożeniowy