> ## 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.

# Metrics

> Response counts, NPS, CSAT, CES and average scores, numbers over time, and breakdowns by the AI's analysis or by where responses came from.

Three endpoints return the numbers the dashboard shows. They need a credential with the `analytics:read` scope.

| Endpoint | Returns |
| - | - |
| [`GET /metrics/summary`](https://docs.usertick.com/developers/api/reference/get-metrics-summary) | The response count, and for one survey its NPS, CSAT, CES and average score |
| [`GET /metrics/timeseries`](https://docs.usertick.com/developers/api/reference/get-metrics-time-series) | One value per day, week or month |
| [`GET /metrics/breakdown`](https://docs.usertick.com/developers/api/reference/get-metrics-breakdown) | Responses per value of one dimension |

All three take `surveyId`, `from` and `to`. A `to` given as a date alone, such as `2026-10-14`, includes that whole UTC day. Without `surveyId`, the numbers cover the whole organization. Without `from` and `to`, they cover everything your plan keeps. A `from` older than your plan's retention window starts at the beginning of the window instead.

## Get the summary

```bash theme={null}
curl "https://app.usertick.com/api/public/v1/metrics/summary?surveyId=7c9e6679-7425-40de-944b-e07fc1f90ae7&from=2026-09-01T00:00:00Z" \
  -H "Authorization: Bearer utk_live_your_key_here"
```

```json theme={null}
{
  "surveyId": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "from": "2026-09-01T00:00:00.000Z",
  "to": null,
  "responses": 412,
  "nps": { "value": 31.443298969072163, "sampleSize": 388, "questionId": "4b1c2d3e-0000-4a5b-8c9d-0e1f2a3b4c5d" },
  "csat": null,
  "ces": null,
  "avgScore": null
}
```

Each score is read from the survey's first question of its kind, the way a number card on a dashboard reads it. A score is `null` without `surveyId`, and when the survey has no question of that kind.

Scores are unrounded. NPS runs from -100 to 100, CSAT is the percent of ratings at or above the satisfied rating (4 of 5, 8 of 10), and CES and the average score are the average answer. Round each value once where you show it: the dashboard shows the NPS above as +31 and an average to one decimal.

## Get a time series

`metric` is `responses` (the default), `nps` or `detractors`. `interval` is `day` (the default), `week` or `month`, in UTC. The `nps` and `detractors` metrics need a `surveyId`.

```bash theme={null}
curl "https://app.usertick.com/api/public/v1/metrics/timeseries?metric=nps&interval=week&surveyId=7c9e6679-7425-40de-944b-e07fc1f90ae7" \
  -H "Authorization: Bearer utk_live_your_key_here"
```

Each point is `{ date, value, count }`, oldest first. For `nps`, `value` is the step's NPS, unrounded, and `0` when `count` is `0`; treat a step with no answers as having no value.

## Get a breakdown

`by` sets the dimension:

| `by` | Counts responses per |
| - | - |
| `type` | Feedback type: bug, idea, complaint, question, praise |
| `urgency` | Urgency: high, medium, low |
| `theme` | Theme in your analysis tree |
| `category` | Category in your analysis tree |
| `sentiment` | Sentiment: negative, neutral, positive |
| `country` | Country, with `unknown` and `other` buckets |
| `device` | Device type, with `unknown` and `other` buckets |

For `country` and `device`, `top` sets how many values come back before the rest are counted under `other`. It takes 1 to 250 and defaults to 12. A value outside that range returns `400` with `PUB-006-005`. The analysis dimensions always return every value.

```json theme={null}
{
  "by": "type",
  "surveyId": null,
  "total": 1280,
  "buckets": [
    { "key": "bug", "label": "Bug", "count": 402 },
    { "key": "idea", "label": "Idea", "count": 311 }
  ]
}
```

Buckets are sorted largest first. The analysis dimensions include corrections people made. A response with several answers can count under more than one value, so the buckets can add up to more than `total`. A response with no value on the dimension, such as one not analyzed yet or one that matched no theme, has no bucket, so the buckets can also add up to less than `total`.

To list the responses behind a bucket, call [`GET /responses`](https://docs.usertick.com/developers/api/reference/list-responses) with the same filter, such as `type=bug`.


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