Widget statistics per widget
const url = 'https://api.getsitecontrol.com/v1/sites/1/widgets/stats/by-widget';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/by-widget \ --header 'Authorization: Bearer <token>'Event counts per widget, in one of two ways.
With widget_ids (up to 100, from list_widgets): every
listed live widget of the site in the order given, zeros without events;
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.
Without widget_ids the period is required: the live widgets with events in
the period, most shown first. Deleted widgets and events without a widget are
left out, so the sum may be below get_widgets_stats.
folder_id, is_active, layout and search narrow either way to the
widgets that match every one given, and then every matched widget is listed,
zero ones too: one call gives the numbers of a folder or of the active
widgets. total is the sum of the listed widgets; use it rather than adding
the items up.
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”Widget ids from list_widgets, up to 100; repeat for several. With them the period is optional
Widget ids from list_widgets, 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
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
Null when the numbers cover the whole life of the widgets
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
The counters of the listed widgets summed: the numbers of the set, use them rather than adding the items up
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
Live widgets by shows, most first, or in the order of widget_ids. Deleted widgets and events without a widget are left out, so the sum may be below the site total.
object
Widget id
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 }, "items": [ { "id": 1, "name": "example", "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