---
title: "Diagnose widgets"
method: GET
path: "/v1/sites/{site_id}/widgets/diagnostics"
tags: ["Widgets"]
---

# Diagnose widgets

`GET /v1/sites/{site_id}/widgets/diagnostics`

## Request

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

Why widgets do not show: the first call for "my widget is not showing", "it
shows on the wrong pages" or "I get no responses". Without `widget_id` it
checks the site (served at all, our code installed, any widget on) and gives
one short row per active widget with its worst cause; with `widget_id` it
checks that widget in the order visitors meet it: on and published, A/B test,
schedule, targeting, stop rules, trigger, whether answers are sent, and where
it showed. Views are the shows Widget statistics count. Each check has a stable `reason` code, what to do (`next_action`),
who can do it (`who`) and facts in `values`; read `who` before promising
anything.

It reads the saved widget, as visitors get it, and changes nothing. Views are
facts, not proof that the current settings show: `install` is unknown when
nothing proves the code either way. At most the 100 newest active widgets are
checked. The meaning of every code and how to word it: the guide
`widgets.diagnostics.read`.

## Path parameters

- `site_id` integer, required

## Query parameters

- `widget_id` integer: A widget id from List widgets, to check it whole

## Response `200`

Successful Response

- WidgetDiagnosis
  - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing found. warning: some visitors, pages, times or widgets do not get it, or a likely mistake. blocking: no visitor gets it. unknown: the source or the rules could not be read, or (install) nothing proves it either way.
  - `widget` DiagnosedWidget
    - `id` integer, required
    - `is_active` boolean, required
    - `layout` 'modal' | 'bar' | 'panel' | 'slide_in' | 'sidebar' | 'fullscreen' | 'inline' | 'other', required: 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. other: a layout the admin no longer offers. "Pop-up" is not a layout: users call any widget a pop-up.
  - `widgets` WidgetDiagnosisRows
    - `by_state` object, required: Active widgets per state; those beyond the 100 checked are unknown
    - `truncated` boolean, required: More widgets than the 20 listed
    - `items` WidgetDiagnosisRow[], required: Blocking first, then warning, unknown, ok; newest first within one
      - `id` integer, required
      - `name` string, nullable
      - `layout` 'modal' | 'bar' | 'panel' | 'slide_in' | 'sidebar' | 'fullscreen' | 'inline' | 'other', required: 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. other: a layout the admin no longer offers. "Pop-up" is not a layout: users call any widget a pop-up.
      - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing found. warning: some visitors, pages, times or widgets do not get it, or a likely mistake. blocking: no visitor gets it. unknown: the source or the rules could not be read, or (install) nothing proves it either way.
      - `check` 'site' | 'install' | 'active_widgets' | 'widget' | 'ab_test' | 'schedule' | 'targeting' | 'frequency' | 'trigger' | 'submit_flow' | 'games' | 'views': site: whether the site's widgets are served at all. install: whether our code is on the site. active_widgets: whether any widget is on. widget: on, and in what visitors load. ab_test: its share in an A/B test. schedule, targeting, trigger: its rules. frequency: its stop rules. submit_flow: whether answers are sent. games: whether a game still has placeholder prize codes. views: where and how often it showed.
      - `reason` 'blocked_suspicious_activity' | 'account_suspended' | 'trial_ended' | 'plan_not_selected' | 'subscription_ended' | 'views_limit' | 'site_deactivated' | 'app_embed_off' | 'code_not_installed' | 'code_not_seen' | 'no_active_widgets' | 'turned_off' | 'not_published' | 'ab_test_share' | 'outside_window' | 'ended' | 'contradictory_conditions' | 'included_and_excluded' | 'exclude_joined_with_or' | 'empty_page_pattern' | 'pattern_read_as_domain' | 'no_trigger' | 'programmatic_only' | 'never_sends' | 'fields_after_send' | 'placeholder_prize_codes' | 'no_recent_views' | 'not_viewed_in_90_days' | 'not_viewed_yet': Why the check is not ok; null on ok. `blocked_suspicious_activity`: Widgets are not served: our automatic check flagged the site's content as suspicious. Only support can review it. `account_suspended`: The account is suspended or paused by our team, or has no plan; no widget is served. Only support can lift it. `trial_ended`: The free trial is over; widgets are not served until the account owner chooses a plan. `plan_not_selected`: No plan was chosen after installing the Shopify app; widgets are not served until the store owner chooses one. `subscription_ended`: The subscription has ended or a payment failed; widgets are not served until the account owner sorts out billing. `views_limit`: The plan's monthly views are used up since `limited_on`; widgets come back with the next billing period or a bigger plan. `site_deactivated`: The site is turned off, by a user or because the plan allows fewer sites; the account owner can turn it on. `app_embed_off`: The Getsitecontrol app embed is off in the store's theme `theme_name` (or its setting is missing) and nothing else loads widgets, so they do not load. Turn it on at `enable_url`. `code_not_installed`: No view has come from this site in the last 90 days while its widgets were turned on: check that the Getsitecontrol code is on it with "Check code" in the admin. `code_not_seen`: No view has come from this site since `site_last_view_on` while its widgets were turned on: check that the Getsitecontrol code is still on it. `no_active_widgets`: No widget on the site is turned on; nothing can show. `turned_off`: The widget is turned off. `not_published`: The widget is on and the site is served, but what visitors load was last updated before this widget was created. Support has to look. `ab_test_share`: The widget is one of `variants` in an A/B test; each visitor gets one of them, so about `share` of visitors can see this one. `outside_window`: The schedule does not hold right now (not begun yet, another day or another time of day); work out the next window from `schedule`. `ended`: The schedule's last date, `ended_on`, is past; it will not show again. `contradictory_conditions`: No visitor can match these audience conditions together (`patterns`). `included_and_excluded`: A page is both targeted and excluded, so it is excluded; with `every_include`, every page the widget targets is excluded. `exclude_joined_with_or`: "Is not" page rules joined with OR exclude only pages that match all of them at once, usually none, so the exclusions do nothing. `empty_page_pattern`: An empty page value matches only the home page. `pattern_read_as_domain`: The first part of this page value is read as a domain (e.g. `blog/post`), so it never matches the site; start a path with `/`. `no_trigger`: "Show on triggers" is chosen, but no trigger is set. `programmatic_only`: The widget never opens on its own: only the site's code, a link or another widget opens it. Deliberate for such widgets; if it should open by itself, set a trigger. `never_sends`: Visitors can fill in the form, but nothing in the widget ever sends the answers. `fields_after_send`: Pages `pages` are shown after the answers were sent; what visitors enter there is never sent. `placeholder_prize_codes`: A game still has the editor's placeholder prize codes (`fields`); visitors are promised codes the store probably does not honour. Replace them with real codes. `no_recent_views`: Not shown in the last 7 days; last shown on `last_view_on`. `not_viewed_in_90_days`: Not shown in the last 90 days. `not_viewed_yet`: Not shown yet since it was created on `created_at`.
      - `views_7d` integer, nullable: Shows in the last 7 days; null when unknown
  - `checks` WidgetDiagnosticCheck[], required: Without `widget_id`: site, install, active_widgets. With it: site, install, widget, ab_test, schedule, targeting, frequency, trigger, submit_flow, games, views
    - `check` 'site' | 'install' | 'active_widgets' | 'widget' | 'ab_test' | 'schedule' | 'targeting' | 'frequency' | 'trigger' | 'submit_flow' | 'games' | 'views', required: site: whether the site's widgets are served at all. install: whether our code is on the site. active_widgets: whether any widget is on. widget: on, and in what visitors load. ab_test: its share in an A/B test. schedule, targeting, trigger: its rules. frequency: its stop rules. submit_flow: whether answers are sent. games: whether a game still has placeholder prize codes. views: where and how often it showed.
    - `state` 'ok' | 'warning' | 'blocking' | 'unknown', required: ok: nothing found. warning: some visitors, pages, times or widgets do not get it, or a likely mistake. blocking: no visitor gets it. unknown: the source or the rules could not be read, or (install) nothing proves it either way.
    - `reason` 'blocked_suspicious_activity' | 'account_suspended' | 'trial_ended' | 'plan_not_selected' | 'subscription_ended' | 'views_limit' | 'site_deactivated' | 'app_embed_off' | 'code_not_installed' | 'code_not_seen' | 'no_active_widgets' | 'turned_off' | 'not_published' | 'ab_test_share' | 'outside_window' | 'ended' | 'contradictory_conditions' | 'included_and_excluded' | 'exclude_joined_with_or' | 'empty_page_pattern' | 'pattern_read_as_domain' | 'no_trigger' | 'programmatic_only' | 'never_sends' | 'fields_after_send' | 'placeholder_prize_codes' | 'no_recent_views' | 'not_viewed_in_90_days' | 'not_viewed_yet': Why the check is not ok; null on ok. `blocked_suspicious_activity`: Widgets are not served: our automatic check flagged the site's content as suspicious. Only support can review it. `account_suspended`: The account is suspended or paused by our team, or has no plan; no widget is served. Only support can lift it. `trial_ended`: The free trial is over; widgets are not served until the account owner chooses a plan. `plan_not_selected`: No plan was chosen after installing the Shopify app; widgets are not served until the store owner chooses one. `subscription_ended`: The subscription has ended or a payment failed; widgets are not served until the account owner sorts out billing. `views_limit`: The plan's monthly views are used up since `limited_on`; widgets come back with the next billing period or a bigger plan. `site_deactivated`: The site is turned off, by a user or because the plan allows fewer sites; the account owner can turn it on. `app_embed_off`: The Getsitecontrol app embed is off in the store's theme `theme_name` (or its setting is missing) and nothing else loads widgets, so they do not load. Turn it on at `enable_url`. `code_not_installed`: No view has come from this site in the last 90 days while its widgets were turned on: check that the Getsitecontrol code is on it with "Check code" in the admin. `code_not_seen`: No view has come from this site since `site_last_view_on` while its widgets were turned on: check that the Getsitecontrol code is still on it. `no_active_widgets`: No widget on the site is turned on; nothing can show. `turned_off`: The widget is turned off. `not_published`: The widget is on and the site is served, but what visitors load was last updated before this widget was created. Support has to look. `ab_test_share`: The widget is one of `variants` in an A/B test; each visitor gets one of them, so about `share` of visitors can see this one. `outside_window`: The schedule does not hold right now (not begun yet, another day or another time of day); work out the next window from `schedule`. `ended`: The schedule's last date, `ended_on`, is past; it will not show again. `contradictory_conditions`: No visitor can match these audience conditions together (`patterns`). `included_and_excluded`: A page is both targeted and excluded, so it is excluded; with `every_include`, every page the widget targets is excluded. `exclude_joined_with_or`: "Is not" page rules joined with OR exclude only pages that match all of them at once, usually none, so the exclusions do nothing. `empty_page_pattern`: An empty page value matches only the home page. `pattern_read_as_domain`: The first part of this page value is read as a domain (e.g. `blog/post`), so it never matches the site; start a path with `/`. `no_trigger`: "Show on triggers" is chosen, but no trigger is set. `programmatic_only`: The widget never opens on its own: only the site's code, a link or another widget opens it. Deliberate for such widgets; if it should open by itself, set a trigger. `never_sends`: Visitors can fill in the form, but nothing in the widget ever sends the answers. `fields_after_send`: Pages `pages` are shown after the answers were sent; what visitors enter there is never sent. `placeholder_prize_codes`: A game still has the editor's placeholder prize codes (`fields`); visitors are promised codes the store probably does not honour. Replace them with real codes. `no_recent_views`: Not shown in the last 7 days; last shown on `last_view_on`. `not_viewed_in_90_days`: Not shown in the last 90 days. `not_viewed_yet`: Not shown yet since it was created on `created_at`.
    - `next_action` 'none' | 'contact_support' | 'upgrade_plan' | 'check_billing' | 'activate_site' | 'check_installation' | 'enable_app_embed' | 'turn_on_widget' | 'edit_schedule' | 'edit_targeting' | 'set_trigger' | 'edit_content', required: none: nothing to do. contact_support: write to support. upgrade_plan, check_billing: the billing screen. activate_site: turn the site on. check_installation: "Check code" in the admin. enable_app_embed: turn on the app embed at `values.shopify.enable_url`. turn_on_widget: `update_widgets` with `is_active: true`. edit_schedule, edit_targeting, set_trigger: the widget's targeting. edit_content: the widget's pages and buttons.
    - `who` 'user' | 'owner' | 'support' | 'none', required: user: an editor of the site fixes it. owner: the account owner, for money, the plan and turning sites on. support: a person on our side decides; never promise the outcome. none: nobody needs to act.
    - `values` object, required: Facts of the check, `{}` when none. site: `limited_on`. install: `site_last_view_on`, `site_views_7d`, `viewed_hosts` (host to views, 7 days), `rendered_at` (when what visitors load was last updated), `shopify` (null without a Shopify store: `readable`, `embed_enabled`, `metafield_ok`, `script_tag`, `theme_name`, `enable_url`, `script_tags_end_on`). active_widgets: `active`, `inactive`, `checked`. widget: `saved_at`, `published_at`, `last_switch` (the newest `list_widget_history` entry), `history_since`. ab_test: `group_id`, `variants`, `share`. schedule: `ended_on`, `schedule`. targeting: `pages`, `all_pages`, `audience`, `audience_keys`, `findings` (each `reason`, `state`, `patterns`). frequency: `stop`. trigger: `start`, `hide`. submit_flow: `pages` (`position`, `ref`), `unread`. games: `fields` (`name`, `codes`). views: `last_view_on`, `views_7d`, `saved_at`, `views_after_save_day`, `by_page`, `by_device`. The schedule, pages, audience, start, hide and stop blocks are those of `get_widget`; `engine: rules` marks rules this check does not read. Days are UTC days.

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: `widget_not_found`: the site has no such widget, or it was deleted
- `422`: Validation failed
- `429`: Rate limited
- `503`: Temporarily unavailable; retry later

---

[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)