---
title: "Get a study"
method: GET
path: "/api/v1/studies/{study_id}"
tags: ["Studies"]
---

# Get a study

`GET /api/v1/studies/{study_id}`

## Request

- Base URL: `https://app.voicepanel.com`
- URL: `https://app.voicepanel.com/api/v1/studies/{study_id}`
- Auth: HTTP bearer

Retrieve a single study by its ID, including its full plan configuration.

## Path parameters

- `study_id` string, required

## Response `200`

Successful response

- Study: A research study
  - `id` string, required: Study ID
  - `account_id` string, required: Account that owns the study
  - `display_name` string, nullable, required: Public-facing study name shown to participants
  - `internal_name` string, nullable, required: Internal name for organization purposes
  - `objective` string, nullable, required: Research objective for the study
  - `context` string, nullable, required: Brand or product context for the AI interviewer
  - `plan` StudyPlan, required
    - `version` string, required
    - `sections` object[], required
      - `intro` string, nullable
      - `steps` union[], required
        - union
          - object
            - `question` string, required
            - `type` 'task', required
            - `task_type` 'visit_website' | 'download_app' | 'open_app' | 'watch_video' | 'generic_instruction', required
            - `expected_duration_seconds` number
          - object
            - `question` string, required
            - `type` 'long_question', required
            - `probing_areas` string, nullable
            - `probing_type` 'none' | 'light' | 'custom'
            - `response_format` 'audio' | 'audio_only' | 'chat_only' | 'chat'
          - object
            - `question` string, required
            - `type` 'single_select', required
            - `options` object[], required
              - …
            - `shuffle_options` boolean, nullable
            - `vertically_align_choices` boolean, nullable
          - object
            - `question` string, required
            - `type` 'multi_select', required
            - `options` object[], required
              - …
            - `shuffle_options` boolean, nullable
            - `vertically_align_choices` boolean, nullable
          - object
            - `question` string, required
            - `type` 'rating_scale', required
            - `options` object[], required
              - …
            - `lowest_rating_label` string, nullable
            - `highest_rating_label` string, nullable
          - object
            - `question` string, required
            - `type` 'ranking', required
            - `options` object[], required
              - …
            - `shuffle_options` boolean, nullable
          - object
            - `question` string, required
            - `type` 'matrix_single_select', required
            - `rows` object[], required
              - …
            - `columns` object[], required
              - …
            - `shuffle_options` boolean, nullable
          - object
            - `question` string, required
            - `type` 'matrix_multi_select', required
            - `rows` object[], required
              - …
            - `columns` object[], required
              - …
            - `shuffle_options` boolean, nullable
          - object
            - `question` string, required
            - `type` 'conversation', required
            - `time_limit_seconds` number, required
            - `conversation_mode` 'no-guide' | 'guide', required
            - `conversation_guide` string, nullable
            - `response_format` 'audio' | 'audio_only' | 'chat_only' | 'chat'
      - `stimulus` union
        - object
          - `id` string
          - `type` 'text', required
          - `content` string, required
          - `name` string, nullable
          - `metadata` object
          - `placement` 'throughout' | 'at-start', nullable
          - `displaySeconds` number, nullable
        - object
          - `id` string
          - `type` 'website' | 'mobile_app' | 'audio' | 'video' | 'youtube' | 'prototype' | 'image' | 'html' | 'offline' | 'none', required
          - `url` string, required
          - `name` string, nullable
          - `label` string, nullable
          - `metadata` object
          - `urlPreview` object, nullable
            - `image` string, nullable, required
            - `title` string, nullable, required
            - `description` string, nullable, required
            - `favicon` string, nullable
            - `error` string, nullable
            - `botProtected` boolean, nullable
          - `placement` 'throughout' | 'at-start', nullable
          - `displaySeconds` number, nullable
          - `sizing` 'fit' | 'fit-width' | 'fit-height', nullable
        - object
          - `id` string
          - `type` 'group', required
          - `stimuli` union[], required
            - union
              - …
          - `showCount` number, required
          - `displaySeconds` number, nullable
          - `sizing` 'fit' | 'fit-width' | 'fit-height', nullable
        - object
          - `id` string
          - `type` 'side_by_side', required
          - `stimuli` object[], required
            - `id` string
            - `type` 'image' | 'html', required
            - `url` string, required
            - `name` string, nullable
            - `label` string, nullable
            - `metadata` object
            - `urlPreview` object, nullable
              - …
            - `placement` 'throughout' | 'at-start', nullable
            - `displaySeconds` number, nullable
            - `sizing` 'fit' | 'fit-width' | 'fit-height', nullable
          - `displaySeconds` number, nullable
          - `sizing` 'fit' | 'fit-width' | 'fit-height', nullable
      - `recording` object, nullable
        - `audio` boolean
        - `video` boolean
        - `screen` boolean
        - `mobile_screen` boolean
      - `conditionalBranch` union
        - object
          - `sourceType` 'segment', required
          - `segmentationKey` string, required
          - `triggerValues` string[], required
        - object
          - `sourceType` 'task', required
          - `sourceSectionIndex` number, required
          - `sourceStepIndex` number, required
          - `triggerValues` string[], required
        - object
          - `sourceType` 'question'
          - `sourceSectionIndex` number, required
          - `sourceStepIndex` number, required
          - `triggerValues` string[], required
    - `randomizations` object[], required
      - `sectionIndices` number[], required
    - `flagged_content` boolean
    - `device` 'any' | 'desktop' | 'mobile' | 'ios' | 'android'
  - `plan_source` 'study.questions' | 'study.plan', required: Field that holds the interview content. Studies created through the API use `study.plan`.
  - `questions` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `brand_logo_url` string, nullable, required: URL of brand logo shown during the interview
  - `brand_words` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `brand_words_generated` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `show_welcome_page` boolean, required: Whether to show a welcome page before starting
  - `welcome_text` string, nullable, required: Custom welcome page text
  - `target_length_min` number, nullable, required: Target interview length in minutes
  - `uniqueness_constraint` 'custom_id_required' | 'custom_id_required_single_submission', nullable, required: Enforce unique responses via custom ID
  - `written_in_language` string, required: Language code the study is written in
  - `is_archived` boolean, required: Whether the study is archived
  - `is_pre_draft` boolean, required: True while an AI-authored study is still being assembled. List endpoints leave these studies out.
  - `enable_tts_default` boolean, required: Whether text-to-speech is enabled by default
  - `tts_voice_id` string, nullable, required: Voice ID for text-to-speech
  - `screen_out_criteria` string, nullable, required: Criteria the AI interviewer uses to screen out a participant
  - `template_id` string, nullable, required: Template the study was created from
  - `authoring_method` 'scratch' | 'ai_chat' | 'template', required: How the study was authored
  - `source` string, nullable, required: Client that created the study: `web`, `api`, or `mcp`
  - `last_edited_source` string, nullable, required: Client that last edited the study
  - `last_modified_at` string, date-time, nullable, required: When the study content last changed
  - `demo_report` union, required
    - string
    - number
    - boolean
    - Json[]
    - object
  - `created_by` string, nullable, required: ID of the user who created the study
  - `created_at` string, date-time, nullable, required
  - `updated_at` string, date-time, nullable, required
  - `tags` Tag[], required: Tags attached to the study
    - `id` string, required: Tag ID
    - `account_id` string, required: Account that owns the tag
    - `name` string, required: Tag name
    - `created_at` string, date-time, required

## Other responses

- `400`: Bad request. `code` is `validation_error` when a field is invalid or a query parameter is unknown, with the field paths in `details`, or `bad_request` otherwise.
- `401`: Unauthorized. The token is missing, invalid, or has no user.
- `403`: Forbidden. The token has no access to this resource.
- `404`: Not found. The resource does not exist or belongs to another account.
- `429`: Too many requests. The account used its API rate limit. `code` is `too_many_requests`. Wait for the number of seconds in `Retry-After`, then retry.
- `500`: Internal error. Quote `request_id` when you contact support.

---

[API](https://skmtc.dev/voicepanel/apis/voicepanel-api.md) - [All operations](https://skmtc.dev/voicepanel/apis/voicepanel-api/llms.txt) - [OpenAPI document](https://skmtc.dev/voicepanel/apis/voicepanel-api/revisions/ee41535c5694?raw)