Site widget statistics
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/stats?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?from=2026-04-15' \ --header 'Authorization: Bearer <token>'Event counts of all widgets of the site over the period, summed; without filters deleted widgets count too. 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. 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. Per widget: Widget statistics per widget; over time: Site widget statistics over time.
Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Query Parameters
Section titled “Query Parameters”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
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
{ "period": { "date_from": "2026-04-15", "date_to": "2026-04-15" }, "matched": 1, "total": { "show": 1, "submit": 1, "openUrl": 1, "showWidget": 1, "addToCart": 1, "applyCoupon": 1, "copyToClipboard": 1 }, "rates": { "submit": 1, "openUrl": 1, "showWidget": 1, "addToCart": 1, "applyCoupon": 1, "copyToClipboard": 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
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