Site widget statistics over time
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/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/widgets/stats/timeline?interval=day&from=2026-04-15' \ --header 'Authorization: Bearer <token>'Event counts of all widgets of the site, split into buckets. widget_ids, folder_id, is_active, layout and search narrow the count to the live widgets that match every one given; matched says how many, and matched: 0 means no widget 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. Counts: show is the widget shown to a visitor (a view), submit a form sent, openUrl a button or link opening a URL, showWidget a button opening another widget, addToCart, applyCoupon and copyToClipboard the matching cart and coupon buttons. rates next to each total gives every action counter divided by show, rounded to 4 places (rates.submit is the conversion rate); a rate is null when show 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 widget ids from list_widgets, up to 100; repeat for several
Only these widget ids from list_widgets, up to 100; repeat for several
True: only widgets that are on; false: only off
True: only widgets that are on; false: only off
Only widgets of this layout; use it only when the user names one
Only widgets of this layout; use it only when the user names one
Part of the name, the id, or words of the widget’s own text
Part of the name, the id, or words of the widget’s own text
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 widgets 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
Event counts keyed by event type; every key is always present.
object
Each action counter of total divided by show, so the conversion rate is rates.submit; every key is always present, null when show is 0
object
submit / show; null when there were no shows: the rate is undefined, not zero
openUrl / show; null when there were no shows: the rate is undefined, not zero
showWidget / show; null when there were no shows: the rate is undefined, not zero
addToCart / show; null when there were no shows: the rate is undefined, not zero
applyCoupon / show; null when there were no shows: the rate is undefined, not zero
copyToClipboard / show; null when there were no shows: 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
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 statistics store timed out or is overloaded; the heavy request is spent all the same
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