Getting Started

Introduction

The Results API is a set of endpoints that can help you analyze and gather in-depth data from test and session results.

Use cases include:

• automated research pipelines
• real-time action triggers and insight delivery
• AI analysis and insight generation
• custom dashboards and internal UX portals

📘

Note: The Results API (v2) works only on the latest test types and the sessions associated with them.

These tests include:

• surveys
• interaction tests

For other test types, see note below.

Overview of test and session results

Within the UserTesting platform, companies receive an account to manage their data. Each account is divided into workspaces to organize data by category. The company grants team members access by workspace. Team members create tests, which are a set of questions or tasks, within each workspace. These tests are then given to participants to answer. Each participant’s interaction with a test is a session. Participants are also grouped into audiences.

Scope of the Results API

Since your client credentials are associated with your email address, the Results API gives you access to the data within the workspaces where your email is used to register you as a team member.

Within the workspaces you have access to, you will be able to fetch the following result types:

• Test results (for interaction tests) return QXscores, which are a measure of participants' experience within each session.
• Session results give you a list of all sessions within a test and can return session details, such as participant demographics and task responses. If working with an interaction test, you can also retrieve session videos and transcripts.

Prerequisites

• Obtain an access token for a user in the workspace you want to work in (ACCESS_TOKEN). Go to the Authorization page for details.

• Obtain the universally unique identifier (UUID) of a test (TEST_ID). Go to How to Obtain a TestId (UUID) for details.

After obtaining the required values for ACCESS_TOKEN and the TEST_ID mentioned in the prerequisites, you’re ready to start working with session and test data.

📘

Note: Each of the endpoints described below uses the following base URL:

https://api.use2.usertesting.com

Working with session results

Fetch all sessions in a test

Let’s begin by getting a list of all the sessions within a test.

Use the testId as a query parameter in the session results endpoint.

• GET /api/v2/sessionResults

Request example (with pagination defaults)

curl --request GET \
     --url 'https://api.use2.usertesting.com/api/v2/sessionResults?testId=TEST_ID' \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Response sample

{
  "testId": "TEST_ID",
  "sessions": [
    {
      "sessionId": "SESSION_ID_00",
      "audienceId": "AUDIENCE_ID_00",
      "status": "COMPLETE",
      "startTime": "2024-11-21T12:23:52.614Z",
      "finishTime": "2024-11-21T12:25:03.347Z"
    },
    {
      "sessionId": "SESSION_ID_01",
      "audienceId": "AUDIENCE_ID_00",
      "status": "COMPLETE",
      "startTime": "2024-11-21T12:28:10.112Z",
      "finishTime": "2024-11-21T12:31:05.203Z"
    },
  ],
  "meta": {
    "pagination": {
      "limit": 25,
      "offset": 0,
      "totalCount": 2
    }
  }
}

Response handling

From the response, grab a session ID from any sessions[ ].sessionId property.

You can then use the sessions[ ].sessionId value as a path parameter on the other session results endpoints to do the following:

• Retrieve session details

• Retrieve a video transcript

• Obtain a video download link

Retrieve session details

If you need in-depth session details, such as session metadata, participant demographics, or task results, use the session ID as a path parameter in the sessionResults endpoint.

• GET /api/v2/sessionResults/SESSION_ID

Request example

curl --request GET \
     --url https://api.use2.usertesting.com/api/v2/sessionResults/SESSION_ID \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Response sample

{
  "sessionId": "SESSION_ID",
  "audienceId": "AUDIENCE_ID",
  "testPlanId": "TEST_PLAN_ID",
  "sessionParticipant": {
    "participantId": "PARTICIPANT_ID",
    "demographicsInfo": [
      {
        "id": "DEMOGRAPHICS_ID",
        "code": "GENDER",
        "label": "What is your gender?",
        "value": "Male",
        "type": "DEMOGRAPHIC_QUESTION_TYPE_SINGLE"
      }
    ]
  },
  "sessionTaskResults": [
    {
      "taskId": "TASK_ID",
      "taskType": "TASK_TYPE_RATING_SCALE",
      "taskResponse": {
        "ratingScaleSpecificFields": {
          "uuid": "RATING_ID",
          "text": "How satisfied are you with our service?",
          "value": "4"
        }
      }
    }
  ]
}

Retrieve a video transcript

To analyze what participants say during a session, you can retrieve the entire video transcript in WebVTT format using the session ID on this endpoint:

• GET /api/v2/sessionResults/SESSION_ID/transcript

Request example

curl --request GET \
     --url https://api.use2.usertesting.com/api/v2/sessionResults/SESSION_ID/transcript \
     --header 'Accept: text/vtt' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Response sample

WEBVTT

00:00:00.000 --> 00:00:02.000
Hello, World!

00:00:02.000 --> 00:00:04.000
This is a VTT example

Obtain a video download link

You can also get links to download session videos to help you make clips or video summaries for stakeholders to watch by using the session ID on this endpoint:

• GET /api/v2/sessionResults/SESSION_ID/videoDownloadUrl

Request example

curl --request GET \
     --url https://api.use2.usertesting.com/api/v2/sessionResults/SESSION_ID/videoDownloadUrl \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Response sample

{
  "videoUrl": "VIDEO_URL",
  "sessionId": "SESSION_ID",
  "expiresAt": "2025-10-01T12:00:00Z"
}

Working with test results

Some test types, such as interaction tests, gather QXscore data. You can obtain the QXscore by using the test ID on this endpoint's path:

• GET /api/v2/testResults/TEST_ID/qxScores

Request example

curl --request GET \
     --url https://api.use2.usertesting.com/api/v2/testResults/TEST_ID/qxScores \
     --header 'Accept: application/json' \
     --header 'Authorization: Bearer ACCESS_TOKEN'

Response sample

{
  "testId": "TEST_ID",
  "qxScores": [
    {
      "taskGroupId": "TASK_GROUP_ID",
      "label": "QXscore 1",
      "qxScore": 38,
      "components": {
        "behavioral": 25,
        "attitudinal": 50
      },
      "values": {
        "behavioral": [
          50,
          50
        ],
        "usability": 50,
        "trust": 50,
        "appearance": 50,
        "loyalty": 50
      }
    }
  ],
  "meta": {
    "totalQxTasks": 1,
    "completes": 2
  }
}

Further resources

Go to the Tutorials section to explore use case implementations.