---
title: "Widget statistics per widget"
method: GET
path: "/v1/sites/{site_id}/widgets/stats/by-widget"
tags: ["Widgets"]
---

# Widget statistics per widget

`GET /v1/sites/{site_id}/widgets/stats/by-widget`

## Request

- Base URL: `https://api.getsitecontrol.com`
- URL: `https://api.getsitecontrol.com/v1/sites/{site_id}/widgets/stats/by-widget`
- Auth: HTTP bearer

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.

## Path parameters

- `site_id` integer, required

## Query parameters

- `widget_ids` integer[]: Widget ids from `list_widgets`, up to 100; repeat for several. With them the period is optional
- `from` string, date: UTC day, included; omit for the whole life
- `to` string, date: UTC day, included; with `from`, today when omitted
- `is_active` boolean: true: only widgets that are on; false: only off
- `layout` 'modal' | 'bar' | 'panel' | 'slide_in' | 'sidebar' | 'fullscreen' | 'inline': Where the widget sits on the page, named as in the admin. modal: a window centred over the page. bar: a strip across the top or bottom of the page. panel: a box attached to the bottom of the screen, opened from its header. slide_in: a box that slides in from a corner. sidebar: a panel attached to the left or right edge of the screen. fullscreen: covers the whole screen. inline: placed inside the page content. "Pop-up" is not a layout: users call any widget a pop-up.
- `search` string: Words of the name in order (case, spacing and punctuation are ignored), the id, or words of the widget's own text
- `folder_id` integer: Only the items of this folder, an id from `list_folders`; 0 is General

## Response `200`

Successful Response

- WidgetStatsBreakdown
  - `period` StatsPeriod
    - `date_from` string, date, required: First day, UTC, included
    - `date_to` string, date, required: Last day, UTC, included
  - `matched` integer, nullable: 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
  - `total` WidgetMetrics, required: Event counts keyed by event type; every key is always present.
    - `show` integer, required
    - `submit` integer, required
    - `openUrl` integer, required
    - `showWidget` integer, required
    - `addToCart` integer, required
    - `applyCoupon` integer, required
    - `copyToClipboard` integer, required
  - `rates` WidgetRates, required: Every action counter of `total` as a share of `show`. A fraction rounded to 4 places: 0.0125 is 1.25%. The counters are events, not people, each dated on its own: a visitor may act more than once per show, and an action in the period may follow a show before it, so a rate can exceed 1.
    - `submit` number, nullable: `submit` / `show`; null when there were no shows: the rate is undefined, not zero
    - `openUrl` number, nullable: `openUrl` / `show`; null when there were no shows: the rate is undefined, not zero
    - `showWidget` number, nullable: `showWidget` / `show`; null when there were no shows: the rate is undefined, not zero
    - `addToCart` number, nullable: `addToCart` / `show`; null when there were no shows: the rate is undefined, not zero
    - `applyCoupon` number, nullable: `applyCoupon` / `show`; null when there were no shows: the rate is undefined, not zero
    - `copyToClipboard` number, nullable: `copyToClipboard` / `show`; null when there were no shows: the rate is undefined, not zero
  - `items` WidgetStatsBreakdownItem[], required: 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.
    - `id` integer, required: Widget id
    - `name` string, nullable
    - `total` WidgetMetrics, required: Event counts keyed by event type; every key is always present.
      - `show` integer, required
      - `submit` integer, required
      - `openUrl` integer, required
      - `showWidget` integer, required
      - `addToCart` integer, required
      - `applyCoupon` integer, required
      - `copyToClipboard` integer, required
    - `rates` WidgetRates, required: Every action counter of `total` as a share of `show`. A fraction rounded to 4 places: 0.0125 is 1.25%. The counters are events, not people, each dated on its own: a visitor may act more than once per show, and an action in the period may follow a show before it, so a rate can exceed 1.
      - `submit` number, nullable: `submit` / `show`; null when there were no shows: the rate is undefined, not zero
      - `openUrl` number, nullable: `openUrl` / `show`; null when there were no shows: the rate is undefined, not zero
      - `showWidget` number, nullable: `showWidget` / `show`; null when there were no shows: the rate is undefined, not zero
      - `addToCart` number, nullable: `addToCart` / `show`; null when there were no shows: the rate is undefined, not zero
      - `applyCoupon` number, nullable: `applyCoupon` / `show`; null when there were no shows: the rate is undefined, not zero
      - `copyToClipboard` number, nullable: `copyToClipboard` / `show`; null when there were no shows: the rate is undefined, not zero

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `422`: Validation failed
- `429`: Rate limited
- `503`: `temporarily_unavailable`: the statistics store timed out or is overloaded; the heavy request is spent all the same

---

[API](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api.md) - [All operations](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/llms.txt) - [OpenAPI document](https://skmtc.dev/getsitecontrol/apis/getsitecontrol-public-api/revisions/084fcad80e75?raw)