UserTesting QXscore Data API
Access Quality of Experience Scores (QXscores) calculated from a test's completed sessions.
OpenAPI Specification
openapi: 3.0.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 QXscore 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: 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](https://help.usertesting.com/hc/en-us/articles/23596817555101-Interaction-tests) based on all completed sessions. The response includes detailed component and subcomponent values that contribute to the overall QXscore.\n \n _Compatibility:_\n - Compatible with interaction tests, i.e., tests with the \"STUDYV2\" type and \"NON_THINK_OUT_LOUD\" product type.\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 _Note:_\n - 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. \n [Learn more about QXscore](https://help.usertesting.com/hc/en-us/articles/22818008129565-QXscore).\n \n _Use case example:_\n - For an example on how to create a UX metrics dashboard with QXscore to track experience quality, go to [Build a UX Metrics Dashboard](https://developer.usertesting.com/v2.0/docs/ux-metrics-dashboard).\n"
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:
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
description: The aggregate score computed from all sessions (participants) that completed the QX task group within the test.
minimum: 0
maximum: 100
nullable: true
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
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
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
QxScoreComponentsDto:
type: object
properties:
behavioral:
type: number
description: The average percentage obtained from sessions (participants) of the QXscore's behavioral component.
minimum: 0
maximum: 100
nullable: true
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
QxScoreValuesDto:
type: object
properties:
behavioral:
description: Array that represents the navigational task scores used to calculate the behavioral component.
nullable: true
example: null
type: array
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.