> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usertick.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Usertick runs surveys on websites, by link, by QR code and by email, and collects every response in one inbox with reports, dashboards and workflows. The REST API lives at https://app.usertick.com/api/public/v1 and uses Bearer API keys or OAuth access tokens; the JavaScript SDK is the @usertick/snippet package on npm.

# Results per question

> Read a survey's results per question as the Results page shows them: counts, averages, NPS, CSAT, rankings, matrix rows and timing, with the same filters.

[`GET /surveys/{surveyId}/results`](https://docs.usertick.com/developers/api/reference/get-survey-results) returns a survey's results per question, as the **Results** page in Usertick reads them, and requires the `analytics:read` scope.

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl "https://app.usertick.com/api/public/v1/surveys/7c9e6679-7425-40de-944b-e07fc1f90ae7/results?from=2026-10-01&channel=website&tz=America/New_York" \
  -H "Authorization: Bearer utk_live_your_key_here"
```

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "surveyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "window": {
    "from": "2026-10-01T00:00:00.000Z",
    "to": null,
    "retentionFrom": null,
    "timeZone": "America/New_York",
    "compared": null
  },
  "summary": { "responses": 412, "thisWeek": 61, "previousWeek": 54, "trendPct": 13, "completionRate": 92.4, "mainScore": { "kind": "nps", "value": 31.44 }, "...": "..." },
  "demographics": { "countries": [{ "key": "US", "count": 220 }], "devices": [{ "key": "Desktop", "count": 301 }], "...": "..." },
  "questions": [
    {
      "id": "4b1c2d3e-0000-4a5b-8c9d-0e1f2a3b4c5d",
      "type": "nps",
      "text": "How likely are you to recommend us?",
      "position": 1,
      "answered": 388,
      "buckets": [{ "key": "0", "count": 12 }, { "key": "10", "count": 140 }],
      "average": 7.9,
      "nps": { "promoters": 190, "passives": 120, "detractors": 78, "score": 28.87 },
      "...": "..."
    }
  ],
  "removedQuestions": [],
  "ignoredFilters": [],
  "partial": false
}
```

## What each question holds

Each question carries the blocks its type fills, and `null` for the others:

| Field | Filled for |
| - | - |
| `buckets` | Scales and choices: a count per answer, keyed the way the Results page labels it (an option's words in the survey's default language, a scale's number, yes or no, a day). Every option is listed, unpicked ones at 0 |
| `average`, `scaleMin`, `scaleMax` | Numeric questions and scales |
| `nps` | NPS questions: promoters, passives, detractors and the score |
| `csat` | Rating questions: the satisfied rating, the satisfied count and the score |
| `rankings`, `rankLimit` | Ranking questions |
| `matrix` | Matrix questions: rows, columns and the cells with answers |
| `range` | Sliders with two handles |
| `pairs` | This or that questions |
| `medianDurationMs`, `timedOut`, `shown` | Time on the question, and for a timed question how many ran out of time |
| `series` | The question over time: one point per day, week or month of the window |
| `previous` | The same question over the window just before (`window.compared`) |

Scores and averages come back unrounded, so round each value once where you show it.

**Written answers, contact details and files aren't here.** Because they are what people wrote and sent, the API returns them as responses. Read them with [`GET /responses`](https://docs.usertick.com/developers/api/reference/list-responses) and `surveyId`, which requires `responses:read`. For the same reason, `removedQuestions` (questions no longer in the survey that have answers) gives each one's answer count and how many distinct values it holds, without the values.

## Filters

The endpoint takes the Results page's filters, and you can combine them.

| Parameter | Takes |
| - | - |
| `from`, `to` | A time window. A `to` given as a date alone includes that whole UTC day |
| `channel` | `website`, `link` or `email` |
| `country` | A country code, such as `US` |
| `device` | `desktop`, `tablet` or `mobile` |
| `language` | A language the responses were answered in |
| `page` | A page responses came from |
| `answer` | `questionId:value`, the value as the question's bucket key reads. Repeat it, up to 50 times |
| `variant` | A variant ID, or `default` |
| `timedOut` | `yes` or `no` |
| `speeders` | `true` for responses faster than a third of the survey's median time |
| `durationMin`, `durationMax` | Total response time in seconds, 0 to 86,400 |
| `tz` | An IANA time zone the daily and weekly steps are cut in (UTC by default) |

When a value goes past what a filter takes, the call returns `400` and names the parameter instead of shortening or ignoring the value. An unknown time zone returns `PUB-001-004`, a filter value longer than any value it can match returns `ANL-010-001`, and more than 50 answer filters return `ANL-010-002`. An answer filter on a question no longer in the survey is listed in `ignoredFilters`, and every other filter still applies.

## The window

As in the dashboard, the results cover what your plan keeps. `window.from` marks where the read starts, which is the `from` you sent, or the start of your plan's response history when that is later. `window.retentionFrom` gives that start, and is `null` when your plan keeps every response.

`partial` is `true` when part of the read didn't come back, such as the series or the window before. What came back is correct, and the missing parts are empty. When nothing can be read, the call returns `503` with `ANL-001-503`, and you can try again.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.