---
title: "List responses of all widgets"
method: GET
path: "/v1/sites/{site_id}/responses"
tags: ["Responses"]
---

# List responses of all widgets

`GET /v1/sites/{site_id}/responses`

## Request

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

Form responses of every widget of the site in one list, oldest first
(ascending id); `order=newest` gives the latest first (descending id). Call it
for the latest responses across the site's widgets, e.g. to summarize what
visitors sent lately; `widget_id` narrows it to some widgets. Each item is
the same as in `list_widget_responses`, its `widget_id` naming the widget
and its `fields` read by that widget's form.

Responses of deleted widgets of the site are included, as by
`list_widget_responses`. A `widget_id` of no widget of the site matches
nothing.

A page holds up to `limit` responses; while `next_cursor` is set, pass it as
`cursor` for the next page with the same `order`, `widget_id`,
`created_since` and `created_before`. Both periods filter by the time a
response was sent.

Completeness is as in `list_widget_responses`: a response awaiting double
opt-in or an e-mail check appears later with its original id and send time,
a deleted one disappears, and `contact_id` may be null on a fresh response.

## Path parameters

- `site_id` integer, required

## Query parameters

- `widget_id` integer[]: Only responses of these widgets, ids from `list_widgets`; repeat for several. Omit for every widget of the site
- `created_since` string, date-time: Sent at or after this moment; without an offset, taken as UTC; a plain date means its start
- `created_before` string, date-time: Sent before this moment; without an offset, taken as UTC; a plain date means its start. A moment later than now is accepted and covers every response sent so far
- `cursor` string: `next_cursor` of the previous page, sent with the same `order`; omit for the first
- `limit` integer: Items per page
- `fields` string: Comma-separated fields to keep in each item, for example `id,name`; each item then carries only those fields and `id`. Omit for every field
- `order` 'oldest' | 'newest': Order of a list. oldest: the oldest item first; newest: the newest item first, for the latest items without paging through the history.

## Response `200`

Successful Response

- WidgetResponsePage: One page of a list; `next_cursor` is null on the last page.
  - `items` WidgetResponse[], required
    - `id` integer, required
    - `number` string, nullable: Response number, when the widget numbers its responses
    - `widget_id` integer, required
    - `created_at` string, date-time, required: When the response was sent
    - `contact_id` integer, nullable: Set asynchronously; may be null on a fresh response
    - `fields` object, required: Answers by field name, in the order of the widget's current form. Options removed from the form since the response are left out.
    - `params` object, required: Visitor parameters as set on the site: arbitrary JSON that may hold personal data
    - `page_url` string, nullable: Page the response was sent from, with its query string, which may hold e-mails or tokens
    - `query` object, required: Query parameters of page_url, the last value of a repeated key; may hold e-mails or tokens
    - `referrer` string, nullable: Previous page of the visit on the site, not the external source; with its query string
    - `source` string, nullable: Page the visit came from, as the browser reported it on the visit's first page: usually another site, with its query string; null for a direct visit
    - `geo` ResponseGeo, required
      - `country` string, nullable
      - `country_code` string, nullable
      - `region` string, nullable
      - `city` string, nullable
    - `utm` ResponseUtm, required
      - `source` string, nullable
      - `medium` string, nullable
      - `campaign` string, nullable
      - `term` string, nullable
      - `content` string, nullable
    - `device` ResponseDevice, required
      - `platform` string, nullable
      - `os` string, nullable
      - `browser` string, nullable
    - `platform` ResponsePlatform, required
      - `type` string, nullable: The site's e-commerce platform, e.g. shopify; null elsewhere
      - `customer_id` string, nullable: The platform's id of a signed-in customer
      - `order_id` string, nullable: The platform's order id, on an order status page
    - `warnings` string[], required: Empty unless the response could not be read; wording is not stable, do not parse
  - `next_cursor` string, nullable

## Other responses

- `400`: Unsupported GSC-Version
- `401`: Missing or invalid API key or access token
- `403`: Access denied
- `404`: Not found
- `422`: `validation_failed`: a malformed parameter, or `created_since` after `created_before`. `invalid_cursor`: the cursor is damaged or was issued for another `order`, `widget_id`, `created_since` or `created_before`
- `429`: `rate_limited`: the key, account or heavy bucket is spent; this operation spends the heavy bucket shared with statistics and other heavy calls
- `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)