Broadcast statistics per broadcast
const url = 'https://api.getsitecontrol.com/v1/sites/1/broadcasts/stats/by-broadcast';const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request GET \ --url https://api.getsitecontrol.com/v1/sites/1/broadcasts/stats/by-broadcast \ --header 'Authorization: Bearer <token>'E-mail numbers per broadcast, in one of two ways.
With broadcast_ids (up to 100, from list_broadcasts): every
listed live broadcast of the site in the order given, zeros without e-mails;
repeated ids count once, unknown, deleted and foreign ids are left out. The
period is optional here: without from and to the numbers cover the whole
life, and period is null. This is how to get the numbers of a page of the
list in one call.
Without broadcast_ids the period is required: up to 100 live
broadcasts by send, most first, including those with activity but no
sending in the period. For the rest pass broadcast_ids. Deleted broadcasts
and e-mails without a broadcast are left out, so the sum may be below
get_broadcasts_stats.
status, search, created_since, started_since, started_before and
folder_id narrow either way to the broadcasts that match every one given,
and then every matched broadcast is listed, zero ones too: one call gives the
numbers of a folder, of the running broadcasts or of the broadcasts sent in a
month. total is the sum of the listed broadcasts; use it
rather than adding the items up.
Each number counts the events dated in the period on its own, so the numbers are independent: a bounce or an open of an e-mail sent before the period counts here too.
Every number counts e-mails, one e-mail being one message to one recipient,
and each e-mail at most once per metric: send e-mails sent, including those
rejected on sending; bounce e-mails that bounced or were rejected on
sending; deliver is send minus bounce, never below zero; open e-mails
opened; click e-mails with at least one link clicked; unsubscribe e-mails
whose recipient unsubscribed through them; complaint e-mails reported as
spam through the recipient’s mail provider. rates next to each total
gives the delivery, open, click, click-to-open, unsubscribe, complaint and
bounce rates, rounded to 4 places; a rate is null when its denominator is 0,
as it is undefined, not zero.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”Broadcast ids from list_broadcasts, up to 100; repeat for several. With them the period is optional
Broadcast ids from list_broadcasts, up to 100; repeat for several. With them the period is optional
UTC day, included; omit for the whole life
UTC day, included; omit for the whole life
UTC day, included; with from, today when omitted
UTC day, included; with from, today when omitted
Only broadcasts in any of these statuses; repeat for several
Only broadcasts in any of these statuses; repeat for several
Part of the name, case ignored, or the exact id
Part of the name, case ignored, or the exact id
Created at or after; without an offset, taken as UTC; a plain date means its start
Created at or after; without an offset, taken as UTC; a plain date means its start
Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start
Sending first started at or after this moment (started_at); without an offset, taken as UTC; a plain date means its start
Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start
Sending first started before this moment, excluded; without an offset, taken as UTC; a plain date means its start
Only the items of this folder, an id from list_folders; 0 is General
Only the items of this folder, an id from list_folders; 0 is General
Responses
Section titled “Responses”object
Null when the numbers cover the whole life of the broadcasts
object
First day, UTC, included
Last day, UTC, included
How many live broadcasts the filters or ids matched; null without them. 0 means nothing matched, not that nothing happened: check the filters or ids
The counters of the listed broadcasts summed: the numbers of the set, use them rather than adding the items up
object
Rates computed from total, so the open rate is rates.open; every key is always present, null when its denominator is 0
object
Delivery rate: deliver / send; null when send is 0: the rate is undefined, not zero
Open rate: open / deliver; null when deliver is 0: the rate is undefined, not zero
Click rate: click / deliver; null when deliver is 0: the rate is undefined, not zero
Click-to-open rate: click / open; null when open is 0: the rate is undefined, not zero. A click is counted without an open when the recipient’s mail app does not load images, so it can exceed 1
Unsubscribe rate: unsubscribe / deliver; null when deliver is 0: the rate is undefined, not zero
Spam complaint rate: complaint / deliver; null when deliver is 0: the rate is undefined, not zero
Bounce rate: bounce / send; null when send is 0: the rate is undefined, not zero
object
Broadcast id
Broadcast name
E-mail counts; every key is always present.
open, click and the rest count each e-mail once. send includes
e-mails rejected on sending, which are also counted in bounce.
complaint is spam complaints reported by mail providers.
For a period, each number counts the events dated in it, so the numbers
are independent: a bounce may fall in a later period than its sending.
deliver is send minus bounce, never below zero.
object
Rates computed from total, so the open rate is rates.open; every key is always present, null when its denominator is 0
object
Delivery rate: deliver / send; null when send is 0: the rate is undefined, not zero
Open rate: open / deliver; null when deliver is 0: the rate is undefined, not zero
Click rate: click / deliver; null when deliver is 0: the rate is undefined, not zero
Click-to-open rate: click / open; null when open is 0: the rate is undefined, not zero. A click is counted without an open when the recipient’s mail app does not load images, so it can exceed 1
Unsubscribe rate: unsubscribe / deliver; null when deliver is 0: the rate is undefined, not zero
Spam complaint rate: complaint / deliver; null when deliver is 0: the rate is undefined, not zero
Bounce rate: bounce / send; null when send is 0: the rate is undefined, not zero
{ "period": { "date_from": "2026-04-15", "date_to": "2026-04-15" }, "matched": 1, "total": { "send": 1, "deliver": 1, "bounce": 1, "open": 1, "click": 1, "unsubscribe": 1, "complaint": 1 }, "rates": { "deliver": 1, "open": 1, "click": 1, "click_to_open": 1, "unsubscribe": 1, "complaint": 1, "bounce": 1 }, "items": [ { "id": 1, "name": "example", "total": { "send": 1, "deliver": 1, "bounce": 1, "open": 1, "click": 1, "unsubscribe": 1, "complaint": 1 }, "rates": { "deliver": 1, "open": 1, "click": 1, "click_to_open": 1, "unsubscribe": 1, "complaint": 1, "bounce": 1 } } ]}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Authentication scheme: Bearer
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
rate_limited: a limit of the key or the account is spent; statistics also spend the heavy request limit of the key. Retry after Retry-After seconds
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds
Seconds until the bucket refills
temporarily_unavailable: the numbers took too long to count or the limits cannot be checked right now; retry later or shorten the period
The documented shape of every error body on the versioned surface.
object
object
{ "type": "example", "title": "example", "status": 1, "detail": "example", "instance": "example", "reason": "example", "next": "example", "request_id": "example", "errors": [ { "loc": [ "example" ], "msg": "example", "type": "example" } ], "metadata": {}}Headers
Section titled “Headers”API version the response was produced for
Request id, echoed from the request when valid
Limit of the tightest bucket
Requests left in its window
End of its window, epoch seconds