Site broadcast statistics over time
const url = 'https://api.getsitecontrol.com/v1/sites/1/broadcasts/stats/timeline?interval=day&from=2026-04-15';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/timeline?interval=day&from=2026-04-15' \ --header 'Authorization: Bearer <token>'E-mail numbers of all broadcasts of the site, without filters deleted ones
included, split into buckets of interval. broadcast_ids, status, search, created_since, started_since,
started_before and folder_id narrow the count to the live broadcasts that
match every one given; matched says how many, and matched: 0 means no
broadcast matched. Buckets are consecutive days, calendar weeks (Monday to Sunday) or calendar
months; the first and the last are cut to the period. Every bucket is
present, an empty one with zeros.
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”Bucket length
Bucket length
First day of the period, UTC, included
First day of the period, UTC, included
Last day of the period, UTC, included; today when omitted
Last day of the period, UTC, included; today when omitted
Only these broadcast ids from list_broadcasts, up to 100; repeat for several
Only these broadcast ids from list_broadcasts, up to 100; repeat for several
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
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
Day, calendar week (Monday to Sunday) or calendar month.
Every bucket of the period in order, empty ones with zeros
One timeline item; the first and the last are clipped to the period.
object
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
{ "interval": "day"}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