UserTesting General Session Data API

openapi: 3.2.0
info:
  title: Results General Session Data API
  description: With the Results API, you can access the results of your UserTesting account's Surveys, Live Conversations, Interaction Tests, and Think-out-loud Tests for analysis and reporting purposes.
  version: '2.0'
  contact:
    name: UserTesting Support
    url: https://developer.usertesting.com/
    email: support@usertesting.com
servers:
- url: https://api.use2.usertesting.com
security:
- bearerAuth: []
tags:
- name: General Session Data
  description: Retrieve session summaries and detailed session results from a test.
paths:
  /api/v2/sessionResults:
    get:
      description: 'Returns a paginated list of summaries for each completed session in a test. Each summary includes the session ID, status, and timestamps.


        In the response, sessions are sorted in descending order, i.e., from newest to oldest.


        _Compatibility:_

        - All tests with the "STUDYV2" type are compatible. These include tests with the following product types:

        - "SURVEY" (survey)

        - "LIVE_CONVERSATION" (non-classic live conversation)

        - "NON_THINK_OUT_LOUD" (interaction test)

        - "THINK_OUT_LOUD" (think-out-loud test)

        - Go to How to Obtain a Test ID (UUID) for details.


        _Best practices:_

        - Always use pagination query parameters (_limit_ and _offset_) along with the appropriate logic to ensure all sessions are retrieved.

        - Use the response data from _limit_, _offset_, and _totalCount_ in the _meta.pagination_ property to calculate the number of pagination iterations (API requests) needed to collect all sessions in the test.


        _Use case examples:_

        - For an example on near real-time polling, go to Stream Insights into Slack or Jira.

        - For an example on how to add session summaries into an automated research data pipeline, go to Create an Automated Pipeline.'
      operationId: SessionResultsController_getSessionSummaryResults
      parameters:
      - name: testId
        required: true
        in: query
        description: ID of the test containing the sessions.
        schema:
          format: uuid
          type: string
      - name: limit
        required: false
        in: query
        description: Maximum number of sessions to return in the result set.
        schema:
          minimum: 1
          maximum: 500
          default: 25
          example: 25
          type: number
      - name: offset
        required: false
        in: query
        description: Number of sessions to skip before starting to collect the result set.
        schema:
          minimum: 0
          maximum: 10000
          default: 0
          example: 0
          type: number
      responses:
        '200':
          description: Session summaries successfully retrieved.
          headers:
            Cache-Control:
              description: Caching policy for the response.
              schema:
                type: string
                example: private, no-store
            Pragma:
              description: HTTP/1.0 backward compatibility for no-cache.
              schema:
                type: string
                example: no-cache
            Strict-Transport-Security:
              description: Enforces secure (HTTP over SSL/TLS) connections to the server.
              schema:
                type: string
                example: max-age=31536000; includeSubDomains
            Content-Length:
              description: The length of the response body in bytes.
              schema:
                type: integer
                example: 256
            Content-Type:
              description: The MIME type of the returned response.
              schema:
                type: string
                example: application/json; charset=utf-8
            x-ratelimit-limit:
              description: The maximum number of requests allowed in the current period.
              schema:
                type: integer
                example: 10
            x-ratelimit-remaining:
              description: The number of requests remaining in the current period.
              schema:
                type: integer
                example: 7
            x-ratelimit-reset:
              description: The time (in seconds) remaining in the current period until the rate limit resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionSummaryResultsResponseDto'
        '400':
          description: Bad request. The offset must be between 0-10000 and limit must be between 1-500.
        '401':
          description: Missing or invalid access token.
        '404':
          description: Test not found.
        '429':
          description: Too many requests. Maximum of 10 requests per minute.
      summary: Find all sessions in a test
      tags:
      - General Session Data
  /api/v3/sessionResults/{sessionId}:
    get:
      description: 'Returns detailed information about a session, including participant demographics, task-group metadata, and individual task responses.


        _Compatibility:_

        - All sessions found within tests with the "STUDYV2" type are compatible. These include tests from the following product types:

        - "SURVEY" (survey)

        - "LIVE_CONVERSATION" (non-classic live conversation)

        - "NON_THINK_OUT_LOUD" (interaction test)

        - "THINK_OUT_LOUD" (think-out-loud test)

        - Go to How to Obtain a Test ID (UUID) for details.


        _Use case examples:_

        - For an example on how to understand and model session-level details and participant demographics, go to Model Session Details & Demographics.

        - For an example on how to add session details into an automated research data pipeline, go to Create an Automated Pipeline.

        - For an example on near real-time polling, go to Stream Insights into Slack or Jira.'
      operationId: SessionResultsV3Controller_getSessionResults
      parameters:
      - name: sessionId
        required: true
        in: path
        description: ID of the session.
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: Session details successfully retrieved.
          headers:
            Cache-Control:
              description: Caching policy for the response.
              schema:
                type: string
                example: private, no-store
            Pragma:
              description: HTTP/1.0 backward compatibility for no-cache.
              schema:
                type: string
                example: no-cache
            Strict-Transport-Security:
              description: Enforces secure (HTTP over SSL/TLS) connections to the server.
              schema:
                type: string
                example: max-age=31536000; includeSubDomains
            Content-Length:
              description: The length of the response body in bytes.
              schema:
                type: integer
                example: 256
            Content-Type:
              description: The MIME type of the returned response.
              schema:
                type: string
                example: application/json; charset=utf-8
            x-ratelimit-limit:
              description: The maximum number of requests allowed in the current period.
              schema:
                type: integer
                example: 10
            x-ratelimit-remaining:
              description: The number of requests remaining in the current period.
              schema:
                type: integer
                example: 7
            x-ratelimit-reset:
              description: The time (in seconds) remaining in the current period until the rate limit resets.
              schema:
                type: integer
                example: 60
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SessionResultsV3ResponseDto'
        '401':
          description: Missing or invalid access token.
        '404':
          description: Session not found.
        '429':
          description: Too many requests. Maximum of 10 requests per minute.
      summary: Retrieve session details (v3)
      tags:
      - General Session Data
components:
  schemas:
    SessionSummaryPaginationDto:
      type: object
      properties:
        limit:
          type: number
          description: Maximum number of sessions returned in the result set.
          example: 25
        offset:
          type: number
          description: Number of sessions skipped before starting to collect the result set.
          example: 0
        totalCount:
          type: number
          description: Total number of sessions within the test.
          example: 1
      required:
      - limit
      - offset
      - totalCount
    TaskResponseDataDto:
      type: object
      properties:
        startTimeMs:
          type: number
          description: Task start time (ms since session start).
          example: 15000
        endTimeMs:
          type: number
          description: Task end time (ms since session start).
          example: 20000
        skipped:
          type: boolean
          description: Whether the participant skipped the task.
          example: false
        answer:
          description: Task-type-specific answer payload.
          allOf:
          - $ref: '#/components/schemas/TaskAnswerDto'
      required:
      - startTimeMs
      - endTimeMs
      - skipped
      - answer
    TaskItemDto:
      type: object
      properties:
        uuid:
          type: string
          description: ID of the task.
          format: uuid
          example: 12debc51-0948-4d2e-9abe-9844ddd5c5ff
        text:
          type: string
          description: Task prompt text.
          example: Rate Website A
        type:
          type: string
          description: "Type of the task.\n  \n  - BLANK: Simple placeholder task. Baseline for test creation.\n  - RATING_SCALE: Likert-style rating scales.\n  - MULTIPLE_CHOICE: Supports single-select and multi-select options. Includes multiSelect, randomizedOptions, and maxLimit metadata when available.\n  - IMAGE: Displays an image in the study. Common in survey-style workflows.\n  - NPS: Captures Net Promoter Score (0-10).\n  - URL: Opens an external URL.\n  - RANK_ORDER: Users rank options (for example: Chocolate, Strawberry, Vanilla, Mint Chocolate).\n  - WRITTEN: Captures spoken responses (think-aloud).\n  - FIGMA: Embeds interactive Figma prototypes. Metadata includes prototypeUrl, figmaPrototypeTitle, and figmaPrototypeDisplaySetting.\n  - MATRIX: Grid-style question for rating multiple items."
          enum:
          - BLANK
          - RATING_SCALE
          - MULTIPLE_CHOICE
          - IMAGE
          - NPS
          - URL
          - RANK_ORDER
          - WRITTEN
          - FIGMA
          - MATRIX
          - UNRECOGNIZED
          example: RATING_SCALE
        response:
          allOf:
          - $ref: '#/components/schemas/TaskResponseDataDto'
      required:
      - uuid
      - text
      - type
      - response
    SessionParticipantDto:
      type: object
      properties:
        participantId:
          type:
          - string
          - 'null'
          description: ID of the participant.
          format: uuid
          example: 41f72104-5f84-44fa-a16a-03f575159611
        demographicsInfo:
          description: Demographic questions and answers.
          type: array
          items:
            $ref: '#/components/schemas/DemographicInfoDto'
      required:
      - participantId
      - demographicsInfo
    SessionSummaryResultItemDto:
      type: object
      properties:
        sessionId:
          type: string
          description: ID of the session.
          format: uuid
          example: 41f72104-5f84-44fa-a16a-03f5751596ec
        audienceId:
          type:
          - string
          - 'null'
          description: Identifier of the audience that the session participant belongs to. Null if session has no assigned audience.
          format: uuid
          example: 41f72104-5f84-44fa-a16a-03f575159611
        status:
          type: string
          description: Session completion status.
          example: COMPLETE
        startTime:
          type: string
          description: Timestamp representing when the session started. UTC timezone. ISO 8601 format.
          example: '2024-11-21T12:23:52.614Z'
          format: date-time
        finishTime:
          type:
          - string
          - 'null'
          description: Timestamp representing when the session finished. UTC timezone. ISO 8601 format.
          example: '2024-11-21T12:25:03.347Z'
          format: date-time
      required:
      - sessionId
      - status
      - startTime
    SessionResultsV3ResponseDto:
      type: object
      properties:
        sessionId:
          type:
          - string
          - 'null'
          description: ID of the session.
          format: uuid
          example: f3c00502-256d-4693-b1b3-7dbd7eb64ca9
        audienceId:
          type:
          - string
          - 'null'
          description: ID of the audience.
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        testPlanId:
          type:
          - string
          - 'null'
          description: ID of the test plan.
          format: uuid
          example: 6ba7b810-9dad-11d1-80b4-00c04fd430c8
        sessionParticipant:
          description: Participant ID and their demographic information.
          allOf:
          - $ref: '#/components/schemas/SessionParticipantDto'
        taskGroups:
          description: List of task groups and their responses. May be empty if the session has no task groups.
          type: array
          items:
            $ref: '#/components/schemas/TaskGroupItemDto'
        tasks:
          description: List of individual tasks and their responses. May be empty if the session has no tasks.
          type: array
          items:
            $ref: '#/components/schemas/TaskItemDto'
      required:
      - sessionId
      - audienceId
      - testPlanId
      - sessionParticipant
      - taskGroups
      - tasks
    SessionSummaryResultsResponseDto:
      type: object
      properties:
        testId:
          type: string
          description: ID of the test queried for session summaries.
          format: uuid
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        sessions:
          description: Collection of session summaries.
          type: array
          items:
            $ref: '#/components/schemas/SessionSummaryResultItemDto'
        meta:
          description: Response metadata.
          allOf:
          - $ref: '#/components/schemas/SessionSummaryResultsMetaDto'
      required:
      - testId
      - sessions
      - meta
    TaskAnswerDto:
      type: object
      properties:
        blank:
          type:
          - object
          - 'null'
          description: Simple placeholder task. Baseline for test creation.
        ratingScale:
          type:
          - object
          - 'null'
          description: Likert-style rating scales.
        multipleChoice:
          type:
          - object
          - 'null'
          description: Supports single-select and multi-select options. Includes multiSelect, randomizedOptions, and maxLimit metadata when available.
        image:
          type:
          - object
          - 'null'
          description: Displays an image in the study. Common in survey-style workflows.
        nps:
          type:
          - object
          - 'null'
          description: Captures Net Promoter Score (0-10).
        url:
          type:
          - object
          - 'null'
          description: Opens an external URL.
        rankOrder:
          type:
          - object
          - 'null'
          description: 'Users rank options (for example: Chocolate, Strawberry, Vanilla, Mint Chocolate).'
        written:
          type:
          - object
          - 'null'
          description: Captures spoken responses (think-aloud).
        figma:
          type:
          - object
          - 'null'
          description: Embeds interactive Figma prototypes. Metadata includes prototypeUrl, figmaPrototypeTitle, and figmaPrototypeDisplaySetting.
        matrix:
          type:
          - object
          - 'null'
          description: Grid-style question for rating multiple items.
    TaskGroupItemDto:
      type: object
      properties:
        uuid:
          type: string
          description: ID of the task group.
          format: uuid
          example: 550e8400-e29b-41d4-a716-446655440000
        type:
          type: string
          description: Type of the task group.
          enum:
          - QX_SCORE
          - BALANCED_COMPARISON
          - UNRECOGNIZED
          example: QX_SCORE
        response:
          description: "Type-specific response payload. Shape is determined by \"type\": \n  - QX_SCORE → { score }\n  - BALANCED_COMPARISON → { sequence }."
          oneOf:
          - $ref: '#/components/schemas/TaskGroupResponseQxScoreDto'
          - $ref: '#/components/schemas/TaskGroupResponseBalancedComparisonDto'
      required:
      - uuid
      - type
      - response
    SessionSummaryResultsMetaDto:
      type: object
      properties:
        pagination:
          description: Pagination metadata for the response.
          allOf:
          - $ref: '#/components/schemas/SessionSummaryPaginationDto'
      required:
      - pagination
    TaskGroupResponseQxScoreDto:
      type: object
      properties:
        score:
          type: number
          description: The participant's QXscore (0-100).
          example: 85
      required:
      - score
    TaskGroupResponseBalancedComparisonDto:
      type: object
      properties:
        sequence:
          type: string
          description: Order in which the participant saw the comparison groups.
          example: BA
      required:
      - sequence
    DemographicInfoDto:
      type: object
      properties:
        id:
          type:
          - string
          - 'null'
          description: ID of the demographic question.
          example: 3f1b8c2e-9a44-4c3d-b8b7-1a7f4c0a9d21
        code:
          type:
          - string
          - 'null'
          description: 'Code or key identifying the demographic question category. For example: GENDER, AGE_GROUP, INTERESTS, or INCOME.'
          example: GENDER
        label:
          type:
          - string
          - 'null'
          description: Human-readable label for the demographic question.
          example: What is your gender?
        value:
          type:
          - string
          - 'null'
          description: Answer(s) selected by the participant. Multiple values are separated by commas.
          example: Male
        type:
          type:
          - string
          - 'null'
          description: The question choice type. For example, single or multiple choice.
          example: DEMOGRAPHIC_QUESTION_TYPE_SINGLE
          enum:
          - DEMOGRAPHIC_QUESTION_TYPE_SINGLE
          - DEMOGRAPHIC_QUESTION_TYPE_MULTIPLE
          - UNRECOGNIZED
      required:
      - id
      - code
      - label
      - value
      - type
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Go to [Authorization](https://developer.usertesting.com/v1.0/docs/authentication-authorization) for information on how to generate an access token.