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);# Requires Insights preview access for the organization.
watchlist = client.email.competitive.watchlist.get(range=30)
entry = next((row for row in watchlist.data if row.name == "Everlane" and row.watchlist_brand_id), None)
if entry is None or entry.watchlist_brand_id is None:
raise ValueError("Add Everlane to the watchlist first")
watchlist_brand_id = entry.watchlist_brand_id
report = client.email.competitive.watchlist.brands.get(watchlist_brand_id, range=30)
print(report.model_dump_json())// Requires Insights preview access for the organization.
client, err := bird.NewClient(option.WithAPIKey(os.Getenv("BIRD_API_KEY")))
if err != nil {
log.Fatal(err)
}
ctx := context.Background()
watchlist, err := client.Email.Competitive.Watchlist.Get(ctx, bird.EmailCompetitiveWatchlistGetParams{Range: 30})
if err != nil {
log.Fatal(err)
}
watchlistBrandID := ""
if watchlist.Data != nil {
for _, row := range *watchlist.Data {
if row.Name != nil && *row.Name == "Everlane" && row.WatchlistBrandId != nil {
watchlistBrandID = string(*row.WatchlistBrandId)
break
}
}
}
if watchlistBrandID == "" {
log.Fatal("Add Everlane to the watchlist first")
}
report, err := client.Email.Competitive.Watchlist.Brands.Get(ctx, watchlistBrandID, bird.EmailCompetitiveWatchlistBrandsGetParams{Range: 30})
if err != nil {
log.Fatal(err)
}
encoded, err := json.MarshalIndent(report, "", " ")
if err != nil {
log.Fatal(err)
}
fmt.Println(string(encoded))// Requires Insights preview access for the organization.
$watchlist = $bird->email->competitive->watchlist->get(['range' => 30]);
$watchlistBrandId = null;
foreach ($watchlist->getData() ?? [] as $row) {
if ($row->getName() === 'Everlane' && $row->getWatchlistBrandId() !== null) {
$watchlistBrandId = $row->getWatchlistBrandId();
break;
}
}
if ($watchlistBrandId === null) {
throw new \RuntimeException('Add Everlane to the watchlist first');
}
$report = $bird->email->competitive->watchlist->brands->get($watchlistBrandId, ['range' => 30]);
var_dump($report);bird email competitive watchlist brands get <watchlist-brand-id>curl -X GET "https://us1.platform.bird.com/v1/email/competitive/watchlist/brands/{watchlist_brand_id}" \
-H "Authorization: Bearer $TOKEN" \
--url-query "range=30"Resposta200
{
"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.
Parâmetros
watchlist_brand_id
string
The watchlist entry to act on.
Parâmetros de consulta
range
integer
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
Payload de resposta
period
object
obrigatório
The period every figure covers.
Mostrar atributos secundários
period.days
integer
obrigatório
Length of the period in days.
period.from
string
obrigatório
Start of the period, inclusive.
period.to
string
obrigatório
End of the period, exclusive. Daily figures therefore run through the previous whole UTC day and never include the one in progress.
brand
object
obrigatório
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.
Mostrar atributos secundários
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
obrigatório
True on the row describing your own workspace's sending.
brand.name
string
obrigatório
The brand's name as it was when the brand was added to the watchlist.
brand.industry
nullable string
obrigatório
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
obrigatório
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.
brand.esp
nullable string
obrigatório
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
obrigatório
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
obrigatório
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
obrigatório
Messages sent in the period.
brand.sends_change_percent
nullable number
obrigatório
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
obrigatório
Average campaigns sent per week over the period.
brand.inbox_placement_rate
nullable number
obrigatório
Share of the brand's observed mail that reached an inbox rather than a spam folder.
brand.read_rate
nullable number
obrigatório
Share of delivered mail that was read.
brand.audience_overlap_rate
nullable number
obrigatório
Share of your own audience the panel also sees receiving this brand's mail. Null on your own row, and null for a competitor the panel measured no overlap with, which is an answer rather than a gap.
brand.last_campaign
nullable object
obrigatório
The most recent campaign observed in the period, or null when none was. Always null on your own row.
Mostrar atributos secundários
brand.last_campaign.id
string
obrigatório
The identifier for this campaign. Use it to fetch this one campaign on its own.
It is a string, and it needs to stay one. The values are long enough that
JavaScript, and any other language that stores every number as a floating point
value, will round them, and a rounded identifier matches no campaign at all.
Compare it and pass it back as text.
brand.last_campaign.subject
string
obrigatório
The subject line the panel saw on this campaign.
brand.last_campaign.sent_at
string
obrigatório
When the panel first saw this campaign arrive.
brand.last_campaign.image_url
nullable string
obrigatório
Where the panel's capture of the rendered email can be fetched, null when it captured none. Panels image only some of what they observe, so an absent creative is an ordinary outcome rather than a failed one. The image is served from the panel's own host rather than from ours, so a page embedding it has to allow that host.
brand.provenance
object
obrigatório
Where each figure on this row came from.
Mostrar atributos secundários
brand.provenance.sends
string
obrigatório
Source of sends and of sends_change_percent, which is derived from it.
Possible values: measured, panel, none
brand.provenance.cadence_per_week
string
obrigatório
Source of cadence_per_week.
Possible values: measured, panel, none
brand.provenance.inbox_placement_rate
string
obrigatório
Source of inbox_placement_rate.
Possible values: measured, panel, none
brand.provenance.read_rate
string
obrigatório
Source of read_rate.
Possible values: measured, panel, none
brand.provenance.audience_overlap_rate
string
obrigatório
Source of audience_overlap_rate.
Possible values: measured, panel, none
brand.provenance.last_campaign
string
obrigatório
Source of last_campaign.
Possible values: measured, panel, none
providers
array of object
obrigatório
Placement per mailbox provider, in the order the panel returned them. Empty when the panel published no breakdown for the brand's domains.
Mostrar atributos secundários
providers.mailbox_provider
string
obrigatório
The provider whose treatment of the brand's mail this row describes.
providers.inbox_rate
number
obrigatório
Share of the brand's mail this provider put in the inbox. Recomputed from what the panel observed across every domain the brand sends from, so a small subdomain cannot move it as much as the brand's main one.
providers.spam_rate
number
obrigatório
Share of the brand's mail this provider put in spam.
providers.workspace_inbox_rate
nullable number
obrigatório
Your own inbox rate at this provider, null when you have not sent or the panel has no breakdown for your sending domain. It is the panel's view of your sending rather than from our own measurement of it, because a measured rate and a rate the panel estimated are not comparable, and this figure exists to be compared with the brand's.
Recursos relacionados
Continue com a documentação, guias e exemplos sobre este tópico. Os recursos estão em inglês.
Entenda o conceitoShould I use a Bird SDK or call the API directly?Siga o percurso de aprendizagemBuild your first integrationGuia de implementaçãoSend your first email
Obtenha um resumo de implementação