> ## Documentation Index
> Fetch the complete documentation index at: https://docs.rallyuxr.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a study by ID



## OpenAPI

````yaml https://api.rallyuxr.com/api/openapi get /studies/{studyId}
openapi: 3.1.0
info:
  title: Rally UXR Developer Docs
  version: '1.0'
servers:
  - url: https://api.rallyuxr.com/api/public/v1
security:
  - bearerAuth: []
tags:
  - name: Forms
    description: Operations on Forms in your workspace
  - name: People
    description: Operations on Person's stored in your workspace
  - name: Person Properties
    description: Operations on workspace level Person Properties
  - name: Populations
    description: Operations on Populations in your workspace
  - name: Segments
    description: Operations on Segments in your workspace
  - name: Studies
    description: Operations on Studies in your workspace
  - name: Participants
    description: Operations on Participants in studies
  - name: Screener
    description: Operations on a study's screener
  - name: Consent Submissions
    description: Operations on Consent Submissions for studies
  - name: Incentives
    description: Operations on Incentives in your workspace
  - name: Messages
    description: Operations on Message activities in your workspace
  - name: Imports
    description: Operations on Imports in your workspace
  - name: Users
    description: Operations on Workspace Users
  - name: Teams
    description: Operations on Teams in your workspace
  - name: Backfills
    description: >-
      Routes that can be used to backfill data into Rally. If you'd like access
      to these apis, please reach out to your Customer Success rep
  - name: Person
    description: Deprecated, use People
paths:
  /studies/{studyId}:
    get:
      tags:
        - Studies
      summary: Get a study by ID
      parameters:
        - $ref: '#/components/parameters/StudyId'
      responses:
        '200':
          description: The study
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StudyWithScreener'
        '401':
          description: Unauthorized
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            text/plain:
              schema:
                type: string
                example: Unauthorized
        '403':
          description: Forbidden
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            text/plain:
              schema:
                type: string
                example: Forbidden
        '404':
          description: Not Found
          content:
            text/plain:
              schema:
                type: string
                example: '{Resource} not found'
        '429':
          description: Too Many Requests
          headers:
            Retry-After:
              $ref: '#/components/headers/Retry-After'
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            text/plain:
              schema:
                type: string
                example: Too Many Requests
        '500':
          description: Internal Server Error
          headers:
            X-RateLimit-Limit:
              $ref: '#/components/headers/X-RateLimit-Limit'
            X-RateLimit-Remaining:
              $ref: '#/components/headers/X-RateLimit-Remaining'
            X-RateLimit-Reset:
              $ref: '#/components/headers/X-RateLimit-Reset'
          content:
            text/plain:
              schema:
                type: string
                example: Internal Server Error
      security:
        - bearerAuth: []
components:
  parameters:
    StudyId:
      schema:
        $ref: '#/components/schemas/StudyId'
      required: true
      name: studyId
      in: path
  headers:
    X-RateLimit-Limit:
      description: The maximum number of requests the client is allowed to make.
      schema:
        type: integer
        format: int32
    X-RateLimit-Remaining:
      description: >-
        The number of requests remaining for the client in the current time
        window.
      schema:
        type: integer
        format: int32
    X-RateLimit-Reset:
      description: >-
        The time at which the current time window ends (in Unix timestamp
        format).
      schema:
        type: integer
        format: int32
    Retry-After:
      description: The number of seconds until the client should retry the request.
      schema:
        type: integer
        format: int32
  schemas:
    StudyWithScreener:
      allOf:
        - $ref: '#/components/schemas/Study'
        - type: object
          properties:
            screener:
              anyOf:
                - $ref: '#/components/schemas/ScreenerResponse'
                - type: 'null'
              description: >-
                The study's screener with all of its questions. Null when the
                study has no screener or the caller cannot read screeners. Not
                included in list responses.
          required:
            - screener
      description: Study object including its screener
    StudyId:
      type: string
    Study:
      type: object
      properties:
        studyId:
          type: string
        studyType:
          allOf:
            - $ref: '#/components/schemas/StudyType'
            - description: The type of study
        recruitmentStrategy:
          allOf:
            - $ref: '#/components/schemas/RecruitmentStrategy'
            - description: The recruitment strategy for the study
        status:
          $ref: '#/components/schemas/StudyStatus'
        studyPlan:
          $ref: '#/components/schemas/StudyPlan'
        createdAt:
          type: string
          format: date-time
        createdFromTemplateId:
          type:
            - string
            - 'null'
          description: >-
            The ID of the template this study was created from, or null if not
            created from a template
        owners:
          type: array
          items:
            $ref: '#/components/schemas/StudyOwner'
      required:
        - studyId
        - studyType
        - recruitmentStrategy
        - status
        - studyPlan
        - createdAt
        - createdFromTemplateId
        - owners
      description: Study object
    ScreenerResponse:
      allOf:
        - $ref: '#/components/schemas/Screener'
        - type: object
          properties:
            questions:
              type: array
              items:
                $ref: '#/components/schemas/ScreenerQuestionResponse'
              description: The screener questions, in display order
          required:
            - questions
      description: A screener with its top-level properties and all questions
    StudyType:
      type: string
      enum:
        - SURVEY
        - INTERVIEWS
        - UNMODERATED_TEST
        - GROUP_INTERVIEW
      description: The type of study. Required if not using a duplicate/study template
    RecruitmentStrategy:
      type: string
      enum:
        - IN_RALLY
        - EXTERNAL
      description: >-
        The recruitment strategy for the study. Required if not using a
        duplicate/study template
    StudyStatus:
      type: string
      enum:
        - DRAFT
        - ACTIVE
        - PAUSED
        - CLOSED
      description: The status of the study
    StudyPlan:
      type: object
      properties:
        name:
          type:
            - string
            - 'null'
          description: The internal name of the study
        externalName:
          type:
            - string
            - 'null'
          description: The external name of the study
        description:
          type:
            - string
            - 'null'
          description: The internal description of the study
        externalDescription:
          type:
            - string
            - 'null'
          description: The external description of the study
        startDate:
          anyOf:
            - type: string
              format: date
              description: The start date of the study in YYYY-MM-DD format
              example: '2025-01-01'
            - type: string
              format: date-time
              description: >-
                The start date of the study in ISO 8601 in UTC(with no offset).
                The time is truncated
              example: '2025-01-01T00:00:00Z'
              deprecated: true
            - type: 'null'
        endDate:
          anyOf:
            - type: string
              format: date
              description: The end date of the study in YYYY-MM-DD format
              example: '2025-01-02'
            - type: string
              format: date-time
              description: >-
                The end date of the study in ISO 8601 in UTC(with no offset).
                The time is truncated
              example: '2025-01-02T00:00:00Z'
              deprecated: true
            - type: 'null'
        researchPlanUrl:
          type:
            - string
            - 'null'
          description: The URL of the research plan
        participationLimit:
          type:
            - number
            - 'null'
          default: 10
          description: The participation limit of the study
        consentFormId:
          type:
            - string
            - 'null'
          description: The ID of the consent form
        incentive:
          $ref: '#/components/schemas/StudyPlanIncentive'
        includeScreener:
          type: boolean
          description: >-
            Whether to include a screener. If type is `SURVEY` the default is
            true, if not then false
        brandingConfigId:
          type:
            - string
            - 'null'
          description: >-
            The ID of the branding configuration. Setting it mirrors changing
            the branding in-app: it also updates the study landing page's button
            color and, when the branding config has a workspace email, the
            study's booking-confirmation, booking-cancellation,
            interview-reminder, and interview-reschedule email defaults. On
            update, pass null to clear the study's branding.
        language:
          $ref: '#/components/schemas/LanguageCode'
        scheduler:
          $ref: '#/components/schemas/StudyPlanScheduler'
      required:
        - name
        - externalName
        - description
        - externalDescription
        - startDate
        - endDate
        - researchPlanUrl
        - participationLimit
        - consentFormId
        - incentive
        - includeScreener
        - brandingConfigId
        - language
      description: Study plan object
    StudyOwner:
      type: object
      properties:
        userId:
          type: string
        emailAccountId:
          type: string
        fullname:
          type:
            - string
            - 'null'
        email:
          type:
            - string
            - 'null'
      required:
        - userId
        - emailAccountId
        - fullname
        - email
      description: Study owner object
    Screener:
      type: object
      properties:
        id:
          type: string
          description: The screener id
        workspaceId:
          type: string
          description: The workspace that owns the screener
        studyId:
          type: string
          description: The study the screener belongs to
        type:
          $ref: '#/components/schemas/ScreenerType'
        showSchedulerToQualified:
          type: boolean
          description: Whether the interview scheduler is shown to respondents who qualify
        qualifyByDefault:
          type: boolean
          description: Whether respondents qualify unless a rule disqualifies them
        externalSurveyId:
          type: string
          description: The id of the linked external survey, when the screener uses one
        surveyMonkeyCollectorId:
          type: string
          description: >-
            The SurveyMonkey collector id, when the screener uses a SurveyMonkey
            survey
        externalSurveySetupStatus:
          $ref: '#/components/schemas/ExternalSurveySetupStatus'
        externalSurveySetupErrorCode:
          type: string
          description: >-
            An error code describing why external survey setup failed, when
            applicable
        externalSurveySetupUpdatedAt:
          type: string
          format: date-time
          description: When the external survey setup status last changed (ISO 8601)
        customLinkUrl:
          type: string
          description: >-
            The custom link respondents use to take an externally hosted
            screener
        customLinkTokensJson:
          type: string
          description: JSON describing the query parameters appended to the custom link
        createdAt:
          type: string
          format: date-time
          description: When the screener was created (ISO 8601)
        updatedAt:
          type: string
          format: date-time
          description: When the screener was last updated (ISO 8601)
      required:
        - id
        - workspaceId
        - studyId
        - type
        - showSchedulerToQualified
        - qualifyByDefault
        - createdAt
        - updatedAt
      description: A study's screener top-level properties
    ScreenerQuestionResponse:
      oneOf:
        - $ref: '#/components/schemas/SimpleScreenerQuestionResponse'
        - $ref: '#/components/schemas/OptionScreenerQuestionResponse'
        - $ref: '#/components/schemas/DropdownScreenerQuestionResponse'
        - $ref: '#/components/schemas/MatrixScreenerQuestionResponse'
      discriminator:
        propertyName: category
        mapping:
          simple:
            $ref: '#/components/schemas/SimpleScreenerQuestionResponse'
          option:
            $ref: '#/components/schemas/OptionScreenerQuestionResponse'
          dropdown:
            $ref: '#/components/schemas/DropdownScreenerQuestionResponse'
          matrix:
            $ref: '#/components/schemas/MatrixScreenerQuestionResponse'
      description: >-
        A screener question. Template-sourced questions are returned expanded
        into their concrete category.
    StudyPlanIncentive:
      type:
        - object
        - 'null'
      properties:
        incentiveType:
          $ref: '#/components/schemas/IncentiveType'
        incentiveBudgetId:
          type:
            - string
            - 'null'
          description: The ID of the incentive budget
        amount:
          type:
            - number
            - 'null'
          description: The amount of the incentive
        currency:
          allOf:
            - $ref: '#/components/schemas/IncentiveCurrencyType'
            - description: The currency of the incentive
        customIncentiveId:
          type:
            - string
            - 'null'
          description: If type is CUSTOM then the ID of the custom incentive
        defaultCustomIncentiveValue:
          type:
            - string
            - 'null'
          description: If type is CUSTOM then the default value of the custom incentive
      required:
        - incentiveType
        - incentiveBudgetId
        - amount
        - customIncentiveId
        - defaultCustomIncentiveValue
      description: The incentive details for the study
    LanguageCode:
      type: string
      enum:
        - en
        - es
        - fr
        - it
        - ro
        - pt
        - pl
        - de
        - nl
        - ja
        - pt_BR
        - ko
        - cs
        - hi
        - sk
        - ar
        - tr
      default: en
      description: The language code for the study
    StudyPlanScheduler:
      type:
        - object
        - 'null'
      properties:
        interviewDurationMinutes:
          type: integer
          description: The planned interview duration in minutes.
          example: 60
      required:
        - interviewDurationMinutes
      description: >-
        Scheduler configuration for the study. Read-only. Populated only when
        `studyType` is `INTERVIEWS` and the study has a configured scheduler;
        otherwise the parent `scheduler` field is null (i.e. for `SURVEY`,
        `UNMODERATED_TEST`, `GROUP_INTERVIEW`, or `INTERVIEWS` studies without a
        scheduler row).
    ScreenerType:
      type: string
      enum:
        - RALLY
        - SURVEY_MONKEY
        - TYPEFORM
        - QUALTRICS
        - CUSTOM_LINK
      description: The type of screener
    ExternalSurveySetupStatus:
      type: string
      enum:
        - IN_PROGRESS
        - READY
        - FAILED
      description: Setup status of an external survey screener
    SimpleScreenerQuestionResponse:
      allOf:
        - $ref: '#/components/schemas/SimpleScreenerQuestion'
        - type: object
          properties:
            isRequired:
              type: boolean
              description: >-
                Whether a response is required before the screener can be
                submitted
            id:
              type: string
              description: The question id
            workspaceId:
              type: string
              description: The workspace that owns the question
            questionTemplateId:
              type: string
              description: Present for questions created from a template
          required:
            - isRequired
            - id
            - workspaceId
      description: A short answer, long answer, date, or number question
    OptionScreenerQuestionResponse:
      allOf:
        - $ref: '#/components/schemas/OptionScreenerQuestion'
        - type: object
          properties:
            isRequired:
              type: boolean
              description: >-
                Whether a response is required before the screener can be
                submitted
            randomizeOrder:
              type: boolean
              description: Whether options are shown in a random order per respondent
            includeOther:
              type: boolean
              description: Whether the question has a free-text "Other" option
            otherDisplayText:
              type: string
              description: The display text of the free-text "Other" option
            includeNoneOfTheAbove:
              type: boolean
              description: Whether the question has a "None of the above" option
            id:
              type: string
              description: The question id
            workspaceId:
              type: string
              description: The workspace that owns the question
            questionTemplateId:
              type: string
              description: Present for questions created from a template
          required:
            - isRequired
            - randomizeOrder
            - includeOther
            - includeNoneOfTheAbove
            - id
            - workspaceId
      description: A single-select or multi-select question
    DropdownScreenerQuestionResponse:
      allOf:
        - $ref: '#/components/schemas/DropdownScreenerQuestion'
        - type: object
          properties:
            isRequired:
              type: boolean
              description: >-
                Whether a response is required before the screener can be
                submitted
            id:
              type: string
              description: The question id
            workspaceId:
              type: string
              description: The workspace that owns the question
            questionTemplateId:
              type: string
              description: Present for questions created from a template
          required:
            - isRequired
            - id
            - workspaceId
      description: A dropdown question (no "Other" or "None of the above")
    MatrixScreenerQuestionResponse:
      allOf:
        - $ref: '#/components/schemas/MatrixScreenerQuestion'
        - type: object
          properties:
            isRequired:
              type: boolean
              description: >-
                Whether a response is required before the screener can be
                submitted
            id:
              type: string
              description: The question id
            workspaceId:
              type: string
              description: The workspace that owns the question
            questionTemplateId:
              type: string
              description: Present for questions created from a template
          required:
            - isRequired
            - id
            - workspaceId
      description: A matrix question with rows and shared columns
    IncentiveType:
      type: string
      enum:
        - MONEY_OR_GIFT_CARD
        - MONEY_OR_GIFT_CARD_WITH_TREMENDOUS
        - EXTERNAL_MONEY_OR_GIFT_CARD
        - CHARITY
        - CUSTOM
        - RESPONDENT_MONEY
        - RECRUITMENT_FEE
      description: The type of incentive
    IncentiveCurrencyType:
      type: string
      enum:
        - USD
        - EUR
        - GBP
        - CAD
        - AUD
        - NZD
      description: The currency of the incentive. Defaults to USD when not provided
    SimpleScreenerQuestion:
      type: object
      properties:
        category:
          type: string
          enum:
            - simple
        type:
          type: string
          enum:
            - SHORT_FORM
            - LONG_FORM
            - DATE
            - NUMBER
          description: >-
            Whether the question collects short text, long text, a date, or a
            number
        name:
          type: string
          description: The question prompt
        description:
          type: string
          description: Optional helper text shown beneath the question prompt
        isRequired:
          type: boolean
          default: true
          description: Whether a response is required before the screener can be submitted
        mappedToPropertyId:
          type: string
          description: Map the response to a person property
      required:
        - category
        - type
        - name
      description: A short answer, long answer, date, or number question
    OptionScreenerQuestion:
      type: object
      properties:
        category:
          type: string
          enum:
            - option
        type:
          type: string
          enum:
            - SINGLE_SELECT
            - MULTI_SELECT
          description: >-
            Whether respondents may select one option (SINGLE_SELECT) or several
            (MULTI_SELECT)
        name:
          type: string
          description: The question prompt
        description:
          type: string
          description: Optional helper text shown beneath the question prompt
        isRequired:
          type: boolean
          default: true
          description: Whether a response is required before the screener can be submitted
        options:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerQuestionOptionValue'
          minItems: 1
          maxItems: 25
          description: The selectable options, in display order
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerQuestionRule'
          description: Qualification or skip logic evaluated against the selected options
        mappedToPropertyId:
          type: string
          description: Map the response to a person property
        randomizeOrder:
          type: boolean
          default: false
          description: Randomize the order options are shown to each respondent
        includeOther:
          type: boolean
          default: false
          description: Add a free-text "Other" option
        otherDisplayText:
          type: string
          description: Cannot be supplied unless includeOther is true
        includeNoneOfTheAbove:
          type: boolean
          default: false
          description: Add a "None of the above" option
      required:
        - category
        - type
        - name
        - options
      description: A single-select or multi-select question
    DropdownScreenerQuestion:
      type: object
      properties:
        category:
          type: string
          enum:
            - dropdown
        type:
          type: string
          enum:
            - DROPDOWN
          description: A dropdown question type
        name:
          type: string
          description: The question prompt
        description:
          type: string
          description: Optional helper text shown beneath the question prompt
        isRequired:
          type: boolean
          default: true
          description: Whether a response is required before the screener can be submitted
        options:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerQuestionOptionValue'
          minItems: 1
          maxItems: 25
          description: The selectable options, in display order
        rules:
          type: array
          items:
            $ref: '#/components/schemas/ScreenerQuestionRule'
          description: Qualification or skip logic evaluated against the selected option
        mappedToPropertyId:
          type: string
          description: Map the response to a person property
      required:
        - category
        - type
        - name
        - options
      description: A dropdown question (no "Other" or "None of the above")
    MatrixScreenerQuestion:
      type: object
      properties:
        category:
          type: string
          enum:
            - matrix
        type:
          type: string
          enum:
            - MATRIX
          description: A matrix question type
        name:
          type: string
          description: The question prompt
        description:
          type: string
          description: Optional helper text shown beneath the question prompt
        isRequired:
          type: boolean
          default: true
          description: Whether a response is required before the screener can be submitted
        rows:
          type: array
          items:
            $ref: '#/components/schemas/MatrixScreenerQuestionRow'
          minItems: 1
          maxItems: 25
          description: The matrix rows
        columns:
          type: array
          items:
            type: string
            maxLength: 40
          minItems: 1
          maxItems: 25
          description: The shared column labels applied to every row
      required:
        - category
        - type
        - name
        - rows
        - columns
      description: A matrix question with rows and shared columns
    ScreenerQuestionOptionValue:
      type: object
      properties:
        value:
          type: string
          description: The display value of the option
        mappedToPropertyOptionId:
          type: string
          description: >-
            The property option this option maps to. Omit to leave the option
            unmapped when the question has a mappedToPropertyId.
      required:
        - value
      description: An option for a select or dropdown question
    ScreenerQuestionRule:
      type: object
      properties:
        operator:
          $ref: '#/components/schemas/ScreenerRuleOperator'
        optionValues:
          type: array
          items:
            type: string
          description: >-
            The option values the operator compares against. Must reference
            question options, or "OTHER"/"NONE" when enabled.
        action:
          $ref: '#/components/schemas/ScreenerRuleAction'
        qualificationLogic:
          $ref: '#/components/schemas/ScreenerQualificationLogic'
      required:
        - operator
        - optionValues
      additionalProperties: false
      description: Qualification or skip logic for a select or dropdown question
    MatrixScreenerQuestionRow:
      type: object
      properties:
        value:
          type: string
          maxLength: 100
          description: The row label
        mappedToPropertyId:
          type: string
          description: Map this row's response to a person property
        columnToPropertyOptionId:
          type: object
          additionalProperties:
            type: string
          description: >-
            Maps a column value to a property option id. Columns missing from
            this map are left unmapped.
      required:
        - value
      description: A row of a matrix question
    ScreenerRuleOperator:
      type: string
      enum:
        - IS_EXACTLY
        - DOESNT_EQUAL
        - INCLUDES_ANY_OF
        - INCLUDES_ALL_OF
        - NOT_INCLUDES_ANY_OF
      description: The comparison applied by a screener question rule
    ScreenerRuleAction:
      oneOf:
        - type: object
          properties:
            type:
              type: string
              enum:
                - END_SCREENER
              description: End the screener when the rule matches
          required:
            - type
          additionalProperties: false
        - type: object
          properties:
            type:
              type: string
              enum:
                - JUMP
              description: Jump to another question when the rule matches
            index:
              type: integer
              description: >-
                The zero-based index of the question to jump to. Must reference
                a question after this one; use END_SCREENER to route past the
                last question.
          required:
            - type
            - index
          additionalProperties: false
      description: What happens when a rule matches. Omit to continue to the next question.
    ScreenerQualificationLogic:
      type: string
      enum:
        - QUALIFY
        - DISQUALIFY
      description: Omit for jump or end actions that only route the response
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````