UserTesting General Session Data API

openapi: 3.2.0
info:
  description: 'API documentation for the legacy UTZ Integrations service (v1).


    This API enables partners and external applications to retrieve and embed UserTesting content, including clips, sessions, and highlight reels, and to access study and workspace metadata. Responses are designed to support rich previews and embedded playback experiences in third-party products.


    Endpoints require bearer token authentication and return standard HTTP error payloads for unauthorized or invalid requests.


    **Note**: This is a revised version of the original OpenAPI specification file. The original file can be found [here](https://github.com/UserTestingEnterprise/integrations/blob/main/docs/swagger.json).'
  title: Integrations (v1) Clip General Session Data API
  version: '1.0'
  contact:
    name: UserTesting Support
    url: https://developer.usertesting.com/
    email: support@usertesting.com
servers:
- url: //api.use2.usertesting.com/usertesting/api
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. \n\n  In the response, sessions are sorted in descending order, i.e., from newest to oldest.\n  \n  _Compatibility:_\n  - All tests with the \"STUDYV2\" type are compatible. These include tests with the following product types:\n    - \"SURVEY\" (survey)\n    - \"LIVE_CONVERSATION\" (non-classic live conversation)\n    - \"NON_THINK_OUT_LOUD\" (interaction test)\n    - \"THINK_OUT_LOUD\" (think-out-loud test) \n  - Go to [How to Obtain a Test ID (UUID)](https://developer.usertesting.com/docs/how-to-obtain-a-testid-uuid) for details.\n  \n  _Best practices:_\n  - Always use pagination query parameters (_limit_ and _offset_) along with the appropriate logic to ensure all sessions are retrieved.\n  - 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.\n  \n  _Use case examples:_\n  - For an example on near real-time polling, go to [Stream Insights into Slack or Jira](https://developer.usertesting.com/v2.0/docs/stream-insights-into-slack-or-jira).\n  - For an example on how to add session summaries into an automated research data pipeline, go to [Create an Automated Pipeline](https://developer.usertesting.com/v2.0/docs/tutorial).\n  "
      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.\n\n  _Compatibility:_\n  - All sessions found within tests with the \"STUDYV2\" type are compatible. These include tests from the following product types:\n    - \"SURVEY\" (survey)\n    - \"LIVE_CONVERSATION\" (non-classic live conversation)\n    - \"NON_THINK_OUT_LOUD\" (interaction test)\n    - \"THINK_OUT_LOUD\" (think-out-loud test)\n  - Go to [How to Obtain a Test ID (UUID)](https://developer.usertesting.com/docs/how-to-obtain-a-testid-uuid) for details.\n\n  _Use case examples:_\n  - For an example on how to understand and model session-level details and participant demographics, go to [Model Session Details & Demographics](https://developer.usertesting.com/v2.0/docs/understand-and-model-session-details-demographics).\n  - For an example on how to add session details into an automated research data pipeline, go to [Create an Automated Pipeline](https://developer.usertesting.com/v2.0/docs/tutorial).\n  - For an example on near real-time polling, go to [Stream Insights into Slack or Jira](https://developer.usertesting.com/v2.0/docs/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:
    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.
    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
    TaskGroupResponseQxScoreDto:
      type: object
      properties:
        score:
          type: number
          description: The participant's QXscore (0-100).
          example: 85
      required:
      - score
    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
    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
    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
    SessionSummaryResultsMetaDto:
      type: object
      properties:
        pagination:
          description: Pagination metadata for the response.
          allOf:
          - $ref: '#/components/schemas/SessionSummaryPaginationDto'
      required:
      - pagination
    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
    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
    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
    TaskGroupResponseBalancedComparisonDto:
      type: object
      properties:
        sequence:
          type: string
          description: Order in which the participant saw the comparison groups.
          example: BA
      required:
      - sequence
    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
  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.