Questions

The questions endpoint allows developers to fetch the basic question text associated with each step of a user test. When retrieving a usertest, you can pull the question text for every step in the sequence, making it possible to display or reference the structure of a study without needing the full participant responses.

Note: The Ballpark API currently does not expose all step configuration details. Certain data, such as multiple-choice options or card definitions for card sort steps, is not available. As a result, it is not yet possible to fully recreate every step type from the API alone.

Example query

From the UserTestNode, we interested in the questions field here:

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

Example response

Please note that responses are not available in the feed until they're finalised, at which point they'll be recorded as UPDATED.

{
  "userTest": {
    "uuid": "ut_645c4faa-5c2d-49b1-85fa-823ffbbbfa17",
    "questions": [
      {
        "type": "STEP_MULTIPLE_CHOICE",
        "title": "How many times a day do you use video conferencing software (like Zoom)?",
        "description": "This include standups, one-on-one meetings and interviews",
        "uuid": "step_multipleChoice_c75d1456-0c35-491b-a359-3a1f098da081"
      },
      {
        "type": "STEP_QUESTION",
        "title": "How do you feel about your video conferencing software?",
        "description": "",
        "uuid": "step_question_cd13fd54-109a-4eee-8055-84649a27a2dc"
      }
    ]
  }
}

Step Types

When querying the questions field on a UserTestNode, each question will have a type field that indicates what kind of step it is. Below are all the possible step types you may encounter:

Survey and Question Steps

• STEP_INSTRUCTION — Provides information or instructions to participants about the user test they are taking

• STEP_QUESTION — A free-form question that allows participants to provide plaintext, date, boolean, or other response types

• STEP_MULTIPLE_CHOICE — Offers participants a choice between multiple predefined options

• STEP_YES_OR_NO — A simple binary yes/no question

• STEP_RATING_SCALE — Asks participants to provide a rating on a defined scale

• STEP_LEGAL_QUESTION — Presents specific legal information for participants to review and accept

Usability Testing Steps

• STEP_PROTOTYPE_TASK — Tests a specific task within a prototype

• STEP_WEBSITE_TASK — Tests a task performed on a live website

• STEP_FIRST_CLICK — Tests what a participant is likely to click first on a screen

• STEP_FIVE_SECOND_TEST — Checks a participant's response after viewing an image for five seconds

Marketing and Design Steps

• STEP_PREFERENCE_TEST — Allows participants to select their preference from a set of options

• STEP_BANNER_AD_TEST — Tests the effectiveness of banner ad copy

• STEP_TAGLINE_COPY_TEST — Tests the effectiveness of tagline or copy text

Card Sorting Steps

• STEP_CARDSORT_OPEN — Participants sort cards into categories they create themselves

• STEP_CARDSORT_CLOSED — Participants sort cards into predefined categories

• STEP_CARDSORT_HYBRID — Participants sort cards into predefined categories or create new ones

AI-Powered Steps

• STEP_AI_INTERVIEW — An AI-moderated interview where the AI asks dynamic follow-up questions based on participant responses