Black-and-white line illustration of a document page with dialogue lines representing transcripts.
Black-and-white line illustration of a document page with dialogue lines representing transcripts.

Fetching responses

Accessing Participant Responses via the API

The responses endpoint provides access to complete participant response objects from a study. Each response includes identifiers, timestamps, status fields, and links to associated data such as transcripts, recordings, and metadata. This makes it possible to query, display, and analyze participant sessions programmatically.

Response data is most easily accessed by selecting the resultsSortFilter field from the UserTestNode. This field returns a JSON-encoded string containing response objects, which must be decoded on the client side after retrieval. It is returned in this fashion due to a specific serialisation layer that allows you to access all the response data in one fast call.

Developers can:

  • Fetch all responses for a given testId or retrieve an individual responseId.

  • Access response metadata such as completion status, rejection flags, and submission times.

  • Follow links to transcripts, media, and feeds for deeper analysis.

  • Use filtering or pagination to handle large datasets efficiently.

Note: Responses act as the entry point to most session data. They provide references to related resources but do not inline heavy assets like transcripts or media files, which must be fetched separately.

Example query

Here we're going to select a UserTestNode using its UUID. For an explanation of how to find a test's UUID, see Projects.

query fetchTests {
  userTest(uuid: "ut_645c4faa-5c2d-49b1-85fa-823ffbbbfa17") {
    pk
    uuid
    questions {
      type
      title
      description
      uuid
    }
    resultsSortFilter
  }
}

Example response

The resultsSortFilter field will return a JSON-encoded string, which will need to be decoded on your side once the response comes back.

Within the JSON will be each response, and within each response is each step response, which contains the step type, step UUID & the respondent's answer for each step. The exact data format changes depending on the step type.

Once decoded, the data will be structured something like this:

{
  "customParamColumns": [],
  "uuid": "ut_74b72d9f-fe10-4ae0-83ee-acc61b431e1b",
  "responses": [
    {
      "status": "COMPLETED",
      "responseUUID": "ut_response_8bf26678-2173-4b98-bce4-39991a3764af",
      "pk": 832308,
      "submittedAt": "2025-09-29T17:31:45.650009+00:00",
      "stepResponses": [
        {
          "type": "STEP_MULTIPLE_CHOICE",
          "stepUuid": "step_multipleChoice_2762520d-9ecd-4986-9092-60ee828b6f4e",
          "skipped": false,
          "answers": [
            {
              "otherValue": null,
              "choiceUuid": "0a7453e8-c47f-4454-b821-463f88fb57e8",
              "type": "MULTIPLE_CHOICE",
              "rank": 1
            }
          ],
          "stepRevision": 0,
          "duration": 14
        },
        {
          "type": "STEP_QUESTION",
          "stepUuid": "step_question_89c1650b-cfe1-49ea-8dde-b7d71f3d0fc6",
          "skipped": false,
          "answers": [{ "type": "TEXT", "value": "Marks and Spencers" }],
          "stepRevision": 0,
          "duration": 16
        },
        {
          "type": "STEP_QUESTION",
          "stepUuid": "step_question_09ce1d81-55e4-4e3a-800b-8cac55b1c499",
          "skipped": false,
          "answers": [
            {
              "type": "TEXT",
              "value": "for me comfort is the main reason I would purchase one item over another, size is another reason, plus it has to match my decor."
            }
          ],
          "stepRevision": 0,
          "duration": 97
        },
        {
          "type": "STEP_MULTIPLE_CHOICE",
          "stepUuid": "step_multipleChoice_521b17a0-8f67-4e28-b61e-20459a80df7d",
          "skipped": false,
          "answers": [
            {
              "otherValue": null,
              "choiceUuid": "b3adafa0-7435-4002-8dba-3bab037f1a41",
              "type": "MULTIPLE_CHOICE",
              "rank": 1
            }
          ],
          "stepRevision": 0,
          "duration": 11
        },
        {
          "type": "STEP_RATING_SCALE",
          "stepUuid": "step_rating_03f34480-e29d-4e86-8925-6985e0a5b562",
          "skipped": false,
          "answers": [{ "type": "INTEGER", "value": 4 }],
          "stepRevision": 0,
          "duration": 9
        },
        {
          "type": "STEP_QUESTION",
          "stepUuid": "step_question_7ccb8d34-cd0d-4a05-b212-b75364aad058",
          "skipped": false,
          "answers": [
            {
              "type": "TEXT",
              "value": "for my stylish classic designs, with clean lines and is minimalistic, this ensures it fits in with any decor, its timeless and lasts a long time."
            }
          ],
          "stepRevision": 0,
          "duration": 80
        },
        {
          "type": "STEP_MULTIPLE_CHOICE",
          "stepUuid": "step_multipleChoice_ba01be3f-02b4-45e1-958f-9921aaeaea97",
          "skipped": false,
          "answers": [
            {
              "otherValue": null,
              "choiceUuid": "9f5ac432-ac75-4252-8d98-cdbdb638c420",
              "type": "MULTIPLE_CHOICE",
              "rank": 1
            }
          ],
          "stepRevision": 0,
          "duration": 15
        },
        {
          "type": "STEP_YES_OR_NO",
          "stepUuid": "step_yesNo_63cd969d-c79b-4e1b-9e49-d9ddc5cca35e",
          "skipped": false,
          "answers": [{ "type": "BOOLEAN", "value": true }],
          "stepRevision": 0,
          "duration": 8
        },
        {
          "type": "STEP_QUESTION",
          "stepUuid": "step_question_ecf3e99c-c184-4c57-8313-b5a6320e81e1",
          "skipped": false,
          "answers": [
            {
              "type": "TEXT",
              "value": "Quality of the materials, these days products seem to be made cheaply and not to last."
            }
          ],
          "stepRevision": 0,
          "duration": 53
        },
        {
          "type": "STEP_QUESTION",
          "stepUuid": "step_question_c98bd8a1-905e-4c44-8e61-ee54f3648866",
          "skipped": false,
          "answers": [
            {
              "type": "TEXT",
              "value": "Making things to last, and maybe even offering a repair service so things can be kept for longer."
            }
          ],
          "stepRevision": 0,
          "duration": 62
        }
      ],
      "recruitment": {
        "participantSource": "Standard",
        "participantId": null,
        "studyId": null
      },
      "device": {
        "model": "Chrome",
        "make": "Web",
        "operatingSystem": "Windows (10)"
      },
      "participant": { "name": "Participant-CWQDD", "email": "", "userId": 41 },
      "duration": 435,
      "customParams": [],
      "hasRecording": true
    }
  ],
  "pk": 238136
}

Tying a response to a question

In our query above we also asked the server to return the text and UUID for each step in the test. You can use the step UUID to tie the answer to the original question text.