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

# Get a survey's results per question

> A survey's results as the Results page in Usertick reads them, per question: answered, counts per option or value, averages, NPS with promoters, passives and detractors, CSAT, rankings, matrix rows, ranges, this-or-that pairs, timing, the series over time and the window before (vs previous), with the summary and where responses came from. It takes the Results filters within the plan's response history (window.from says where the read starts). A filter past its bound is 400, never shortened: an unknown time zone is 400 PUB-001-004. Written answers, contact details and files are left out: they are responses, read with responses:read (GET /responses?surveyId=). partial is true when part of the read failed.

Scopes: analytics:read.



## OpenAPI

````yaml api-reference/openapi.json GET /surveys/{surveyId}/results
openapi: 3.1.0
info:
  title: Usertick Public API
  version: 1.0.0
  description: >-
    The Usertick REST API v1: responses, surveys, metrics, contacts, email sends
    and webhook subscriptions of one organization.


    **Authentication.** Send an API key (Settings, Developers, API keys;
    utk_...) or an app's OAuth access token (uto_...) as Authorization: Bearer.
    X-Api-Key works for clients that cannot set Authorization. Each endpoint
    lists the scopes it needs. API keys work on Pro plans and up, and apps such
    as Zapier on every plan. AI assistants reach the API only through the
    Usertick MCP server (Starter and up), never with their token directly.


    **Format.** Plain JSON resources; times are RFC 3339 in UTC with
    milliseconds (2026-09-30T10:00:00.000Z). Lists are { data, nextCursor }:
    limit is 1 to 100 (default 25, out of range is 400), and nextCursor goes
    back as cursor until it is null. A page starts strictly after the last row
    of the page before, so a row deleted or renamed in between never ends a list
    early.


    **Errors.** Every error is { statusCode, success: false, code, message, data
    }, plus errors: [{ field, code, message }] for invalid fields. Switch on
    code (x-error-codes lists them all); messages may change. A path with no
    route answers 404 GEN-000-404, a method the route doesn't take 405
    GEN-000-405 and a body that is not JSON 415 GEN-000-415, in the same
    envelope.


    **Rate limits.** The plan sets the requests a minute, as token buckets: 300
    per credential and 1,500 per organization on Business, 120 and 600 on the
    other plans, and an Enterprise plan may set its own. GET /me returns the
    ones that apply. An answer to an authenticated request has
    X-RateLimit-Limit, -Remaining and -Reset (seconds until the budget is full)
    for the credential, and X-RateLimit-Org-* for the organization, except a 429
    over the credential's budget, which has the credential's only, and
    X-RateLimit-Window: 60s. Over a budget is 429 with Retry-After, the seconds
    the bucket takes to refill one request. A 401 carries no X-RateLimit
    headers, and neither does a 429 GEN-429-001 from the per-address limit
    (3,000 requests a minute per client address, checked before the credential).
    Calls from the Usertick MCP server skip the per-address limit, since every
    assistant arrives from its addresses; the per-credential and
    per-organization budgets still apply to them.


    **Idempotency.** Every POST, and the PATCH of a survey, dashboard or
    workflow draft, takes an Idempotency-Key header: the same key and request
    within 24 hours get the first answer again. A refusal that depends on state
    (a 403, a 409 or a 429) and a server error are not kept, so the same request
    with the key runs again.


    **Survey drafts.** With surveys:draft an assistant or a script creates
    surveys as drafts, copies any survey into a draft and edits the ones never
    published; a person publishes them in Usertick. With surveys:archive it
    archives surveys and restores archived ones as drafts.


    **Contacts and email.** With contacts:read and contacts:write a script
    manages contacts, lists and their members, and erases a contact with every
    response of the person (POST /contacts/{contactId}/erase, with
    responses:delete). With email:read it reads the survey email sends; sending
    stays in Usertick.


    **Dashboards and workflows.** With dashboards:draft an assistant or a script
    creates dashboards as drafts and edits their drafts; with workflows:draft it
    creates workflows switched off and edits their drafts. A person publishes
    either one in Usertick. dashboards:read and workflows:read list and read
    them.


    **Exports.** With exports:create (and responses:read) a script starts CSV or
    Excel exports of a survey's Results or of a dashboard, the files the Export
    menu makes, and downloads them for 24 hours. Each file counts as one of the
    plan's exports a month.


    **Support tickets.** With support:read and support:write an app or an AI
    assistant opens support tickets for the member it signed in as, lists that
    member's tickets and replies on them. A ticket belongs to a person, so an
    API key can't carry these scopes. Support tickets come with the paid plans.


    **Versioning.** Within /v1 changes are additive only: new endpoints, new
    optional parameters, new fields (ignore fields you do not know). Anything
    that will go away is announced at least six months ahead with Deprecation
    and Sunset headers on its answers.


    **Webhooks.** Every delivery is { id, type, createdAt, data }, signed per
    Standard Webhooks (see webhooks). data is the Response resource, with change
    on response.status_changed and response.classification_corrected; on
    theme.spiking it is the spike.


    Every answer carries X-Request-Id.
  contact:
    name: Usertick support
    url: https://usertick.com/support
servers:
  - url: https://app.usertick.com/api/public/v1
    description: Production
security:
  - bearerAuth: []
  - apiKeyHeader: []
tags:
  - name: Account
  - name: Responses
  - name: Surveys
  - name: Metrics
  - name: Exports
  - name: Contacts
  - name: Email
  - name: Dashboards
  - name: Workflows
  - name: Support
  - name: Webhooks
paths:
  /surveys/{surveyId}/results:
    get:
      tags:
        - Metrics
      summary: Get a survey's results per question
      description: >-
        A survey's results as the Results page in Usertick reads them, per
        question: answered, counts per option or value, averages, NPS with
        promoters, passives and detractors, CSAT, rankings, matrix rows, ranges,
        this-or-that pairs, timing, the series over time and the window before
        (vs previous), with the summary and where responses came from. It takes
        the Results filters within the plan's response history (window.from says
        where the read starts). A filter past its bound is 400, never shortened:
        an unknown time zone is 400 PUB-001-004. Written answers, contact
        details and files are left out: they are responses, read with
        responses:read (GET /responses?surveyId=). partial is true when part of
        the read failed.


        Scopes: analytics:read.
      operationId: getSurveyResults
      parameters:
        - name: surveyId
          in: path
          description: A survey id.
          required: true
          schema:
            type: string
            format: uuid
        - $ref: '#/components/parameters/From'
        - $ref: '#/components/parameters/To'
        - name: channel
          in: query
          description: website, link or email.
          required: false
          schema:
            type: string
            enum:
              - website
              - link
              - email
        - name: country
          in: query
          description: A country code (ISO 3166, US).
          required: false
          schema:
            type: string
            maxLength: 16
        - name: device
          in: query
          description: desktop, tablet or mobile.
          required: false
          schema:
            type: string
            enum:
              - desktop
              - tablet
              - mobile
        - name: language
          in: query
          description: A language tag the responses were answered in.
          required: false
          schema:
            type: string
            maxLength: 35
        - name: page
          in: query
          description: >-
            A page responses came from (a path or a URL), as the Pages list keys
            it.
          required: false
          schema:
            type: string
            maxLength: 2048
        - name: answer
          in: query
          description: >-
            questionId:value, the value as the question's bucket key reads (an
            option's words, a number, yes or no). Repeat it, at most 50; they
            combine. A filter on a question no longer in the survey is listed in
            ignoredFilters.
          required: false
          schema:
            type: array
            items:
              type: string
              maxLength: 600
            maxItems: 50
          style: form
          explode: true
        - name: variant
          in: query
          description: A variant id (v_...) or default.
          required: false
          schema:
            type: string
            maxLength: 64
        - name: timedOut
          in: query
          description: >-
            yes: responses where a timer ran out; no: timed responses where none
            did.
          required: false
          schema:
            type: string
            enum:
              - 'yes'
              - 'no'
        - name: speeders
          in: query
          description: 'true: responses faster than a third of the survey''s median time.'
          required: false
          schema:
            type: boolean
        - name: durationMin
          in: query
          description: The shortest total response time, in seconds (0 to 86,400).
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 86400
        - name: durationMax
          in: query
          description: The longest total response time, in seconds (0 to 86,400).
          required: false
          schema:
            type: integer
            minimum: 0
            maximum: 86400
        - name: tz
          in: query
          description: >-
            An IANA time zone the daily and weekly steps are cut in (UTC by
            default).
          required: false
          schema:
            type: string
            maxLength: 64
            examples:
              - Europe/Istanbul
      responses:
        '200':
          description: The results.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
            X-RateLimit-Limit:
              $ref: '#/components/headers/XRateLimitLimit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/XRateLimitRemaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/XRateLimitReset'
            X-RateLimit-Org-Limit:
              $ref: '#/components/headers/XRateLimitOrgLimit'
            X-RateLimit-Org-Remaining:
              $ref: '#/components/headers/XRateLimitOrgRemaining'
            X-RateLimit-Org-Reset:
              $ref: '#/components/headers/XRateLimitOrgReset'
            X-RateLimit-Window:
              $ref: '#/components/headers/XRateLimitWindow'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyResults'
        '400':
          description: >-
            The request isn't valid. Codes: PUB-001-003, PUB-001-004,
            PUB-001-007, ANL-010-001, ANL-010-002.
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                PUB-001-003:
                  $ref: '#/components/examples/PUB-001-003'
                PUB-001-004:
                  $ref: '#/components/examples/PUB-001-004'
                PUB-001-007:
                  $ref: '#/components/examples/PUB-001-007'
                ANL-010-001:
                  $ref: '#/components/examples/ANL-010-001'
                ANL-010-002:
                  $ref: '#/components/examples/ANL-010-002'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          description: 'The resource couldn''t be found. Codes: APK-006-005.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                APK-006-005:
                  $ref: '#/components/examples/APK-006-005'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '503':
          description: 'A data store didn''t respond. Try again. Codes: ANL-001-503.'
          headers:
            X-Request-Id:
              $ref: '#/components/headers/XRequestId'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
              examples:
                ANL-001-503:
                  $ref: '#/components/examples/ANL-001-503'
components:
  parameters:
    From:
      name: from
      in: query
      description: From this time (RFC 3339; UTC when no offset).
      required: false
      schema:
        type: string
        format: date-time
    To:
      name: to
      in: query
      description: >-
        Up to this time (RFC 3339; UTC when no offset). A date alone
        (2026-10-14) includes that whole UTC day.
      required: false
      schema:
        type: string
        format: date-time
  headers:
    XRequestId:
      description: >-
        This answer's id (req_ and 32 hex characters), also in the logs. Quote
        it to support.
      schema:
        type: string
    XRateLimitLimit:
      description: The credential's requests per minute.
      schema:
        type: integer
    XRateLimitRemaining:
      description: What is left of it now.
      schema:
        type: integer
    XRateLimitReset:
      description: >-
        Seconds until the credential's budget is full again (the bucket refills
        continuously).
      schema:
        type: integer
    XRateLimitOrgLimit:
      description: Every credential of the organization together, per minute.
      schema:
        type: integer
    XRateLimitOrgRemaining:
      description: What is left of the organization's budget.
      schema:
        type: integer
    XRateLimitOrgReset:
      description: Seconds until the organization's budget is full again.
      schema:
        type: integer
    XRateLimitWindow:
      description: >-
        The window both budgets count over: 60s, since they are requests per
        minute.
      schema:
        type: string
    RetryAfter:
      description: >-
        Seconds to wait before trying again. On a 429 over a budget, the time
        the bucket takes to refill one request (1 second at 120 or 300 a
        minute); X-RateLimit-Reset says when the whole budget is back.
      schema:
        type: integer
  schemas:
    SurveyResults:
      type: object
      properties:
        surveyId:
          type: string
          format: uuid
        window:
          type: object
          properties:
            from:
              type:
                - string
                - 'null'
              format: date-time
              examples:
                - '2026-09-30T10:00:00.000Z'
              description: >-
                Where the read starts: from, or the start of the plan's response
                history when that is later.
            to:
              type:
                - string
                - 'null'
              format: date-time
              examples:
                - '2026-09-30T10:00:00.000Z'
            retentionFrom:
              type:
                - string
                - 'null'
              format: date-time
              examples:
                - '2026-09-30T10:00:00.000Z'
              description: >-
                The start of the plan's response history; null when the plan
                keeps all of it.
            timeZone:
              type: string
              description: >-
                The zone the daily and weekly steps are cut in (tz, UTC by
                default).
            compared:
              oneOf:
                - type: object
                  properties:
                    from:
                      type: string
                      format: date-time
                      examples:
                        - '2026-09-30T10:00:00.000Z'
                    to:
                      type: string
                      format: date-time
                      examples:
                        - '2026-09-30T10:00:00.000Z'
                  required:
                    - from
                    - to
                  additionalProperties: false
                - type: 'null'
              description: >-
                The window previous is read over: as long, just before; null for
                all time or when the plan hides part of it.
          required:
            - from
            - to
            - retentionFrom
            - timeZone
            - compared
          additionalProperties: false
        summary:
          type: object
          properties:
            responses:
              type: integer
            thisWeek:
              type: integer
              description: The last 7 days in the window's time zone, today counted.
            previousWeek:
              type: integer
            trendPct:
              type:
                - integer
                - 'null'
              description: >-
                Week over week change in whole percent; null when the week
                before had fewer than 10 responses.
            completionRate:
              type:
                - number
                - 'null'
              description: >-
                Percent, unrounded: the average share of the questions each
                response answered.
            firstResponseAt:
              type:
                - string
                - 'null'
              format: date-time
              examples:
                - '2026-09-30T10:00:00.000Z'
            lastResponseAt:
              type:
                - string
                - 'null'
              format: date-time
              examples:
                - '2026-09-30T10:00:00.000Z'
            mainScore:
              oneOf:
                - type: object
                  properties:
                    kind:
                      type: string
                      enum:
                        - nps
                        - rating
                        - ces
                    value:
                      type: number
                  required:
                    - kind
                    - value
                  additionalProperties: false
                - type: 'null'
              description: >-
                The survey's headline score when it has an NPS, rating or CES
                question.
            daily:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
              description: Responses per day (yyyy-MM-dd).
            medianCompletionMs:
              type:
                - integer
                - 'null'
            completionSampleCount:
              type: integer
          required:
            - responses
            - thisWeek
            - previousWeek
            - trendPct
            - completionRate
            - firstResponseAt
            - lastResponseAt
            - mainScore
            - daily
            - medianCompletionMs
            - completionSampleCount
          additionalProperties: false
        demographics:
          type: object
          properties:
            countries:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            languages:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            devices:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            browsers:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            pages:
              type: array
              items:
                $ref: '#/components/schemas/KeyCount'
              description: >-
                The pages with the most answers, at most 8, the rest under
                __other__.
          required:
            - countries
            - languages
            - devices
            - browsers
            - pages
          additionalProperties: false
        questions:
          type: array
          items:
            $ref: '#/components/schemas/QuestionResult'
          description: In survey order.
        removedQuestions:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
              answered:
                type: integer
              valueCount:
                type: integer
                description: How many distinct values its answers hold.
            required:
              - id
              - answered
              - valueCount
            additionalProperties: false
          description: >-
            Questions no longer in the survey that have answers in the window.
            Their values are left out, since a removed text question's values
            are written answers.
        ignoredFilters:
          type: array
          items:
            type: object
            properties:
              kind:
                type: string
                enum:
                  - answer
              questionId:
                type: string
              value:
                type: string
              reason:
                type: string
                enum:
                  - question_removed
            required:
              - kind
              - questionId
              - value
              - reason
            additionalProperties: false
          description: >-
            Answer filters that named a question no longer in the survey; every
            other filter applied.
        partial:
          type: boolean
          description: >-
            True when part of the read failed (the series, the window before or
            the device split): what came back is right, and the missing parts
            are empty.
      required:
        - surveyId
        - window
        - summary
        - demographics
        - questions
        - removedQuestions
        - ignoredFilters
        - partial
      description: >-
        A survey's results as aggregates. Written answers, contact details and
        files are responses, read with responses:read.
      additionalProperties: false
    Error:
      type: object
      properties:
        statusCode:
          type: integer
          description: The HTTP status, again.
        success:
          type: boolean
          description: Always false.
        code:
          type: string
          description: >-
            What went wrong, stable across versions (see x-error-codes). For
            invalid fields, the first field's code.
          examples:
            - PUB-001-001
        message:
          type:
            - string
            - 'null'
          description: The code's message in English (US); null for a code without one.
        data:
          description: Extra context for some errors; null otherwise.
        errors:
          type: array
          items:
            $ref: '#/components/schemas/FieldError'
          description: >-
            Every invalid field, in the order of the request's parameters. Only
            on a 400 about fields.
      required:
        - statusCode
        - success
        - code
        - message
        - data
      description: >-
        Every error answer. Success answers are the plain resource or list
        instead.
      additionalProperties: false
      examples:
        - statusCode: 400
          success: false
          code: PUB-001-001
          message: The limit must be between 1 and 100.
          data: null
          errors:
            - field: limit
              code: PUB-001-001
              message: The limit must be between 1 and 100.
            - field: sort
              code: PUB-001-005
              message: The sort order must be asc or desc.
    KeyCount:
      type: object
      properties:
        key:
          type: string
        count:
          type: integer
      required:
        - key
        - count
      additionalProperties: false
    QuestionResult:
      type: object
      properties:
        id:
          type: string
          description: The question id.
        type:
          type: string
          examples:
            - nps
            - rating
            - multiple_choice
        text:
          type: string
          description: In the survey's default language.
        position:
          type: integer
        answered:
          type: integer
        shown:
          type:
            - integer
            - 'null'
          description: Responses that showed it; null when it has no time limit.
        buckets:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            - type: 'null'
          description: >-
            Counts by the answer as the Results page labels it: an option's
            words in the default language, a scale's number, yes or no, a day.
            Every option is listed, unpicked ones at 0.
        otherLabel:
          type:
            - string
            - 'null'
          description: >-
            The bucket key the Other answers count under; null without an Other
            choice.
        average:
          type:
            - number
            - 'null'
          description: Unrounded.
        scaleMin:
          type:
            - number
            - 'null'
        scaleMax:
          type:
            - number
            - 'null'
        nps:
          oneOf:
            - $ref: '#/components/schemas/NpsSplit'
            - type: 'null'
        csat:
          oneOf:
            - $ref: '#/components/schemas/Csat'
            - type: 'null'
        rankings:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/RankRow'
            - type: 'null'
        rankLimit:
          type:
            - integer
            - 'null'
          description: A ranking that asked for the top N only.
        matrix:
          oneOf:
            - $ref: '#/components/schemas/MatrixResult'
            - type: 'null'
        range:
          oneOf:
            - $ref: '#/components/schemas/RangeResult'
            - type: 'null'
        pairs:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/PairResult'
            - type: 'null'
        medianDurationMs:
          type:
            - integer
            - 'null'
          description: Median time on the question; null when no answer carries a time.
        durationSampleCount:
          type: integer
        timedOut:
          type:
            - integer
            - 'null'
          description: >-
            Responses that ran out of time on it; null when it has no time
            limit.
        series:
          oneOf:
            - $ref: '#/components/schemas/QuestionSeries'
            - type: 'null'
        previous:
          oneOf:
            - $ref: '#/components/schemas/PreviousAnswers'
            - type: 'null'
      required:
        - id
        - type
        - text
        - position
        - answered
        - shown
        - buckets
        - otherLabel
        - average
        - scaleMin
        - scaleMax
        - nps
        - csat
        - rankings
        - rankLimit
        - matrix
        - range
        - pairs
        - medianDurationMs
        - durationSampleCount
        - timedOut
        - series
        - previous
      description: >-
        One question's answers, filled by its type. Written answers, contact
        details and files are not here: they are responses (GET
        /responses?surveyId=).
      additionalProperties: false
    FieldError:
      type: object
      properties:
        field:
          type: string
          description: >-
            The query parameter, or the body property (camelCase, dotted when
            nested).
        code:
          type: string
        message:
          type:
            - string
            - 'null'
      required:
        - field
        - code
        - message
      additionalProperties: false
    NpsSplit:
      type: object
      properties:
        promoters:
          type: integer
        passives:
          type: integer
        detractors:
          type: integer
        score:
          type: number
          description: NPS from -100 to 100, unrounded; 0 without answers.
      required:
        - promoters
        - passives
        - detractors
        - score
      additionalProperties: false
    Csat:
      type: object
      properties:
        satisfiedFrom:
          type:
            - integer
            - 'null'
          description: >-
            The lowest rating that counts as satisfied: ceil(0.8 × scale), 4 of
            5.
        satisfied:
          type: integer
        score:
          type: number
          description: The percent of ratings at or above satisfiedFrom, unrounded.
      required:
        - satisfiedFrom
        - satisfied
        - score
      additionalProperties: false
    RankRow:
      type: object
      properties:
        label:
          type: string
        averagePosition:
          type:
            - number
            - 'null'
          description: Null for an option nobody placed.
        firstPlace:
          type: integer
        ranked:
          type: integer
          description: >-
            People who placed it: everyone in a full ranking, those who put it
            in their top rankLimit otherwise.
      required:
        - label
        - averagePosition
        - firstPlace
        - ranked
      additionalProperties: false
    MatrixResult:
      type: object
      properties:
        rows:
          type: array
          items:
            type: string
        columns:
          type: array
          items:
            type: string
        cells:
          type: array
          items:
            $ref: '#/components/schemas/MatrixCell'
          description: Only the cells with answers.
        multiple:
          type: boolean
          description: >-
            Each row took several answers, so a row's cells can add up past its
            respondents.
        rowAnswered:
          type: array
          items:
            type: integer
          description: 'Per row: respondents who gave it a real answer.'
        notApplicable:
          oneOf:
            - type: array
              items:
                type: integer
            - type: 'null'
          description: >-
            Per row: respondents who marked it Not applicable; null when the
            matrix offers none.
        notApplicableLabel:
          type:
            - string
            - 'null'
      required:
        - rows
        - columns
        - cells
        - multiple
        - rowAnswered
        - notApplicable
        - notApplicableLabel
      additionalProperties: false
    RangeResult:
      type: object
      properties:
        answered:
          type: integer
        averageLow:
          type: number
        averageHigh:
          type: number
        coverage:
          type: array
          items:
            $ref: '#/components/schemas/KeyCount'
          description: 'Along the track: how many answers'' spans include each value.'
      required:
        - answered
        - averageLow
        - averageHigh
        - coverage
      description: 'A slider with two handles: the answers as spans.'
      additionalProperties: false
    PairResult:
      type: object
      properties:
        a:
          $ref: '#/components/schemas/PairSide'
        b:
          $ref: '#/components/schemas/PairSide'
        answered:
          type: integer
      required:
        - a
        - b
        - answered
      additionalProperties: false
    QuestionSeries:
      type: object
      properties:
        grain:
          type: string
          enum:
            - day
            - week
            - month
        points:
          type: array
          items:
            $ref: '#/components/schemas/SeriesPoint'
          description: Oldest first, every step of the window.
        partial:
          type: boolean
          description: >-
            A step held more distinct answers than the read keeps per step
            (300), so its rarest answers are missing.
      required:
        - grain
        - points
        - partial
      additionalProperties: false
    PreviousAnswers:
      type: object
      properties:
        answered:
          type: integer
        buckets:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            - type: 'null'
        average:
          type:
            - number
            - 'null'
        nps:
          oneOf:
            - $ref: '#/components/schemas/NpsSplit'
            - type: 'null'
        pairs:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/PairResult'
            - type: 'null'
      required:
        - answered
        - buckets
        - average
        - nps
        - pairs
      description: The same question over the window before (window.compared).
      additionalProperties: false
    MatrixCell:
      type: object
      properties:
        row:
          type: integer
          description: Index in rows.
        column:
          type: integer
          description: Index in columns.
        count:
          type: integer
      required:
        - row
        - column
        - count
      additionalProperties: false
    PairSide:
      type: object
      properties:
        key:
          type: string
          description: The side's words.
        value:
          type: string
          description: The stored value an answer filter matches.
        count:
          type: integer
      required:
        - key
        - value
        - count
      additionalProperties: false
    SeriesPoint:
      type: object
      properties:
        date:
          type: string
          description: The step's first day (yyyy-MM-dd) in the window's time zone.
        answered:
          type: integer
        responses:
          type: integer
          description: The survey's responses in the step.
        average:
          type:
            - number
            - 'null'
        q1:
          type:
            - number
            - 'null'
        median:
          type:
            - number
            - 'null'
        q3:
          type:
            - number
            - 'null'
        counts:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/KeyCount'
            - type: 'null'
        averages:
          oneOf:
            - type: array
              items:
                $ref: '#/components/schemas/KeyAverage'
            - type: 'null'
          description: >-
            A ranking's average place per option, or an allocation's average
            points.
        rowAverages:
          oneOf:
            - type: array
              items:
                type:
                  - number
                  - 'null'
            - type: 'null'
          description: 'A matrix: per row, the average column (1 is the first).'
      required:
        - date
        - answered
        - responses
        - average
        - q1
        - median
        - q3
        - counts
        - averages
        - rowAverages
      additionalProperties: false
    KeyAverage:
      type: object
      properties:
        key:
          type: string
        average:
          type: number
        count:
          type: integer
      required:
        - key
        - average
        - count
      additionalProperties: false
  examples:
    PUB-001-003:
      summary: Send times in RFC 3339, such as 2026-09-30T10:00:00.000Z.
      value:
        statusCode: 400
        success: false
        code: PUB-001-003
        message: Send times in RFC 3339, such as 2026-09-30T10:00:00.000Z.
        data: null
    PUB-001-004:
      summary: This value isn't valid.
      value:
        statusCode: 400
        success: false
        code: PUB-001-004
        message: This value isn't valid.
        data: null
    PUB-001-007:
      summary: The start of the window must come before its end.
      value:
        statusCode: 400
        success: false
        code: PUB-001-007
        message: The start of the window must come before its end.
        data: null
    ANL-010-001:
      summary: >-
        A filter value is longer than any value it can match. Clear the filter
        and pick its value again.
      value:
        statusCode: 400
        success: false
        code: ANL-010-001
        message: >-
          A filter value is longer than any value it can match. Clear the filter
          and pick its value again.
        data: null
    ANL-010-002:
      summary: >-
        A request can filter by at most 50 answers. Remove some answer filters
        and try again.
      value:
        statusCode: 400
        success: false
        code: ANL-010-002
        message: >-
          A request can filter by at most 50 answers. Remove some answer filters
          and try again.
        data: null
    APK-006-005:
      summary: The survey couldn't be found.
      value:
        statusCode: 404
        success: false
        code: APK-006-005
        message: The survey couldn't be found.
        data: null
    ANL-001-503:
      summary: The results aren't available right now. Try again in a moment.
      value:
        statusCode: 503
        success: false
        code: ANL-001-503
        message: The results aren't available right now. Try again in a moment.
        data: null
    APK-004-001:
      summary: Send an API key or an access token in the Authorization header.
      value:
        statusCode: 401
        success: false
        code: APK-004-001
        message: Send an API key or an access token in the Authorization header.
        data: null
    APK-004-002:
      summary: >-
        The API key or access token is invalid, expired or revoked. Connect
        again with a valid one.
      value:
        statusCode: 401
        success: false
        code: APK-004-002
        message: >-
          The API key or access token is invalid, expired or revoked. Connect
          again with a valid one.
        data: null
    APK-004-007:
      summary: >-
        This credential is for another server. The MCP server takes only the
        access tokens an assistant gets when it signs in, and the REST API takes
        API keys and app tokens.
      value:
        statusCode: 401
        success: false
        code: APK-004-007
        message: >-
          This credential is for another server. The MCP server takes only the
          access tokens an assistant gets when it signs in, and the REST API
          takes API keys and app tokens.
        data: null
    APK-004-004:
      summary: >-
        This API key or app doesn't have permission for this request. Grant it
        the required scope.
      value:
        statusCode: 403
        success: false
        code: APK-004-004
        message: >-
          This API key or app doesn't have permission for this request. Grant it
          the required scope.
        data: null
    APK-004-005:
      summary: >-
        Your plan doesn't include API keys. To use them, upgrade to Pro or
        higher.
      value:
        statusCode: 403
        success: false
        code: APK-004-005
        message: >-
          Your plan doesn't include API keys. To use them, upgrade to Pro or
          higher.
        data: null
    APK-004-008:
      summary: >-
        This organization's plan doesn't include apps that use the API, such as
        Zapier. To use them, contact Usertick sales to change the plan.
      value:
        statusCode: 403
        success: false
        code: APK-004-008
        message: >-
          This organization's plan doesn't include apps that use the API, such
          as Zapier. To use them, contact Usertick sales to change the plan.
        data: null
    APK-004-009:
      summary: >-
        This organization's plan doesn't include the MCP server. To use an AI
        assistant with Usertick, upgrade to Starter or higher.
      value:
        statusCode: 403
        success: false
        code: APK-004-009
        message: >-
          This organization's plan doesn't include the MCP server. To use an AI
          assistant with Usertick, upgrade to Starter or higher.
        data: null
    AUTHZ-001-001:
      summary: You aren't a member of this organization.
      value:
        statusCode: 403
        success: false
        code: AUTHZ-001-001
        message: You aren't a member of this organization.
        data: null
    AUTHZ-001-002:
      summary: Your role doesn't have the required permission.
      value:
        statusCode: 403
        success: false
        code: AUTHZ-001-002
        message: Your role doesn't have the required permission.
        data: null
    APK-004-003:
      summary: This API key or app sent too many requests. Wait a minute and try again.
      value:
        statusCode: 429
        success: false
        code: APK-004-003
        message: >-
          This API key or app sent too many requests. Wait a minute and try
          again.
        data: null
    APK-004-006:
      summary: >-
        Your organization sent too many API requests. Wait a minute and try
        again.
      value:
        statusCode: 429
        success: false
        code: APK-004-006
        message: >-
          Your organization sent too many API requests. Wait a minute and try
          again.
        data: null
    GEN-429-001:
      summary: Too many requests were sent. Wait a minute and try again.
      value:
        statusCode: 429
        success: false
        code: GEN-429-001
        message: Too many requests were sent. Wait a minute and try again.
        data: null
  responses:
    Unauthorized:
      description: >-
        No credential, one that is invalid, expired or revoked, or a token an AI
        assistant got for the MCP server. Codes: APK-004-001, APK-004-002,
        APK-004-007.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            APK-004-001:
              $ref: '#/components/examples/APK-004-001'
            APK-004-002:
              $ref: '#/components/examples/APK-004-002'
            APK-004-007:
              $ref: '#/components/examples/APK-004-007'
    Forbidden:
      description: >-
        The credential lacks a scope this endpoint needs, the plan does not
        include the API (API keys on Pro and up; apps such as Zapier on every
        plan, unless a custom plan leaves them out; AI assistants through the
        Usertick MCP server on Starter and up), or the member an app or an
        assistant acts as lacks the permission (AUTHZ-001-002; AUTHZ-001-001
        when the check names no reason). Codes: APK-004-004, APK-004-005,
        APK-004-008, APK-004-009, AUTHZ-001-001, AUTHZ-001-002.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            APK-004-004:
              $ref: '#/components/examples/APK-004-004'
            APK-004-005:
              $ref: '#/components/examples/APK-004-005'
            APK-004-008:
              $ref: '#/components/examples/APK-004-008'
            APK-004-009:
              $ref: '#/components/examples/APK-004-009'
            AUTHZ-001-001:
              $ref: '#/components/examples/AUTHZ-001-001'
            AUTHZ-001-002:
              $ref: '#/components/examples/AUTHZ-001-002'
    TooManyRequests:
      description: >-
        Over the credential's or the organization's budget, or over the
        per-address limit that is checked before the credential (GEN-429-001,
        without X-RateLimit headers). Codes: APK-004-003, APK-004-006,
        GEN-429-001.
      headers:
        X-Request-Id:
          $ref: '#/components/headers/XRequestId'
        Retry-After:
          $ref: '#/components/headers/RetryAfter'
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            APK-004-003:
              $ref: '#/components/examples/APK-004-003'
            APK-004-006:
              $ref: '#/components/examples/APK-004-006'
            GEN-429-001:
              $ref: '#/components/examples/GEN-429-001'
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: An API key (utk_live_...) or an app's OAuth access token (uto_...).
    apiKeyHeader:
      type: apiKey
      in: header
      name: X-Api-Key
      description: The API key, for clients that cannot send Authorization.

````

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