UserTesting QXscore Data API

openapi: 3.2.0
info:
  title: Results QXscore 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: QXscore Data
  description: Access Quality of Experience Scores (QXscores) calculated from a test's completed sessions.
paths:
  /api/v2/testResults/{testId}/qxScores:
    get:
      description: 'Calculates the Quality of Experience Score (QXscore) for an Interaction test based on all completed sessions. The response includes detailed component and subcomponent values that contribute to the overall QXscore.


        _Compatibility:_

        - Compatible with interaction tests, i.e., tests with the "STUDYV2" type and "NON_THINK_OUT_LOUD" product type.

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


        _Note:_

        - A _QXscore_ is a reliable benchmark metric for evaluating the quality of an experience. This composite score combines behavioral data from navigation tasks with attitudinal data from a standardized questionnaire to effectively balance participants'' actions and opinions.

        Learn more about QXscore.


        _Use case example:_

        - For an example on how to create a UX metrics dashboard with QXscore to track experience quality, go to Build a UX Metrics Dashboard.'
      operationId: TestResultsController_getQxScoreResponse
      parameters:
      - name: testId
        required: true
        in: path
        description: ID of the Interaction test whose QXscore you want to retrieve.
        schema:
          format: uuid
          type: string
      responses:
        '200':
          description: QXscore successfully returned.
          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/QxScoreResponseApi'
        '401':
          description: Missing or invalid access token.
        '404':
          description: Test not found.
        '429':
          description: Too many requests. Maximum of 10 requests per minute.
      summary: Obtain QXscores for a test
      tags:
      - QXscore Data
components:
  schemas:
    QxScoreMetaDto:
      type: object
      properties:
        totalQxTasks:
          type: number
          description: Total number of QX task groups.
          example: 1
        completes:
          type: number
          description: Number of completed sessions.
          example: 2
      required:
      - totalQxTasks
      - completes
    QxScoreComponentsDto:
      type: object
      properties:
        behavioral:
          type:
          - number
          - 'null'
          description: The average percentage obtained from sessions (participants) of the QXscore's behavioral component.
          minimum: 0
          maximum: 100
          example: null
        attitudinal:
          type: number
          description: The average percentage obtained from sessions (participants) of the QXscore's attitudinal component.
          minimum: 0
          maximum: 100
          example: 50
      required:
      - behavioral
      - attitudinal
    QxScoreResponseApi:
      type: object
      properties:
        testId:
          type: string
          description: UUID of the test.
          example: 3fa85f64-5717-4562-b3fc-2c963f66afa6
        qxScores:
          description: List of QXscore results for each QX task group within the test.
          type: array
          items:
            $ref: '#/components/schemas/QxScoreItemDto'
        meta:
          description: Metadata about the QXscore calculation.
          allOf:
          - $ref: '#/components/schemas/QxScoreMetaDto'
      required:
      - testId
      - qxScores
      - meta
    QxScoreItemDto:
      type: object
      properties:
        taskGroupId:
          type: string
          description: UUID of a QX task group within the test that contains a set of navigational tasks and questions used to measure to the QXscore.
          example: b1e2c3d4-5678-1234-9abc-def012345678
        label:
          type: string
          description: Label for the QX task group.
          example: QXscore 1
        qxScore:
          type:
          - number
          - 'null'
          description: The aggregate score computed from all sessions (participants) that completed the QX task group within the test.
          minimum: 0
          maximum: 100
          example: null
        components:
          description: The behavioral and attitudinal QXscore components used to calculate the overall QXscore.
          allOf:
          - $ref: '#/components/schemas/QxScoreComponentsDto'
        values:
          description: Detailed QXscore subcomponent values obtained from session (participant) averages used to calculate the behavioral and attitudinal components.
          allOf:
          - $ref: '#/components/schemas/QxScoreValuesDto'
      required:
      - taskGroupId
      - label
      - qxScore
      - components
      - values
    QxScoreValuesDto:
      type: object
      properties:
        behavioral:
          description: Array that represents the navigational task scores used to calculate the behavioral component.
          example: null
          type:
          - array
          - 'null'
          items:
            type: number
        usability:
          type: number
          description: Represents the usability score used to calculate the attitudinal component.
          minimum: 0
          maximum: 100
          example: 50
        trust:
          type: number
          description: Represents the trust score used to calculate the attitudinal component.
          minimum: 0
          maximum: 100
          example: 50
        appearance:
          type: number
          description: Represents the appearance score used to calculate the attitudinal component.
          minimum: 0
          maximum: 100
          example: 50
        loyalty:
          type: number
          description: Represents the loyalty score used to calculate the attitudinal component.
          minimum: 0
          maximum: 100
          example: 50
      required:
      - behavioral
      - usability
      - trust
      - appearance
      - loyalty
  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.