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

# List surveys

> List surveys in the authenticated workspace. Pagination is offset-based (`limit` + `offset`, default 25, max 100) and always applied.



## OpenAPI

````yaml /openapi/program.openapi.json get /surveys
openapi: 3.1.0
info:
  title: Questra Program API
  version: 0.0.1
  description: >-
    REST API for the Questra Program product. Browser users authenticate through
    Questra Auth SSO; automation uses workspace-scoped API keys (`Authorization:
    Bearer qpk_live_…`). API keys carry scopes enforced before handlers.
    Outbound webhooks follow Standard Webhooks (at-least-once delivery;
    consumers must be idempotent).
servers:
  - url: /v1
    description: Program API base path
security: []
paths:
  /surveys:
    get:
      tags:
        - Surveys
      summary: List surveys
      description: >-
        List surveys in the authenticated workspace. Pagination is offset-based
        (`limit` + `offset`, default 25, max 100) and always applied.
      parameters:
        - schema:
            type: integer
            minimum: 1
            maximum: 100
            description: Page size (default 25, max 100).
          required: false
          description: Page size (default 25, max 100).
          name: limit
          in: query
        - schema:
            type:
              - integer
              - 'null'
            minimum: 0
            description: Rows to skip (default 0).
          required: false
          description: Rows to skip (default 0).
          name: offset
          in: query
        - schema:
            type: string
            description: Case-insensitive search across name, slug, and description.
          required: false
          description: Case-insensitive search across name, slug, and description.
          name: q
          in: query
        - schema:
            type: string
            enum:
              - name
              - created_at
              - updated_at
            description: Sort column (default `updated_at`).
          required: false
          description: Sort column (default `updated_at`).
          name: sort_by
          in: query
        - schema:
            type: string
            enum:
              - asc
              - desc
            description: Sort direction (default `desc`).
          required: false
          description: Sort direction (default `desc`).
          name: sort_order
          in: query
        - schema:
            anyOf:
              - type: string
              - type: array
                items:
                  type: string
            description: >-
              Lifecycle statuses to include (OR). Repeat the param or
              comma-separate. Omit for all.
          required: false
          description: >-
            Lifecycle statuses to include (OR). Repeat the param or
            comma-separate. Omit for all.
          name: status
          in: query
      responses:
        '200':
          description: Paginated survey list
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SurveyList'
        '400':
          description: Validation error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ValidationErrorBody'
components:
  schemas:
    SurveyList:
      type: object
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Survey'
        pagination:
          $ref: '#/components/schemas/OffsetPagination'
      required:
        - data
        - pagination
    ValidationErrorBody:
      type: object
      properties:
        error:
          type: string
          enum:
            - validation_error
        message:
          type: string
        details: {}
      required:
        - error
    Survey:
      type: object
      properties:
        id:
          type: string
          format: uuid
        slug:
          type: string
          minLength: 1
        name:
          type: string
          minLength: 1
        description:
          type: string
        status:
          $ref: '#/components/schemas/SurveyStatus'
        programming_target:
          $ref: '#/components/schemas/ProgrammingTarget'
        list_summary:
          $ref: '#/components/schemas/SurveyListSummary'
        created_at:
          type: string
          format: date-time
        updated_at:
          type: string
          format: date-time
      required:
        - id
        - slug
        - name
        - status
        - programming_target
        - list_summary
        - created_at
        - updated_at
    OffsetPagination:
      type: object
      properties:
        total:
          type: integer
          minimum: 0
          description: Total matching rows across all pages.
        limit:
          type: integer
          exclusiveMinimum: 0
          description: Page size applied to this response.
        offset:
          type: integer
          minimum: 0
          description: Rows skipped before this page.
      required:
        - total
        - limit
        - offset
    SurveyStatus:
      type: string
      enum:
        - inspection
        - programming
        - reviewing
        - live
        - closed
    ProgrammingTarget:
      type:
        - object
        - 'null'
      properties:
        survey_id:
          type: string
          format: uuid
        platform:
          $ref: '#/components/schemas/ProgrammingPlatform'
        instructions:
          type:
            - string
            - 'null'
        fine_tuning_template_id:
          type:
            - string
            - 'null'
          format: uuid
          description: >-
            Fine-tuning template applied to this survey, or null when none is
            chosen.
        config:
          type: object
          additionalProperties: {}
        initial_push_succeeded:
          type: boolean
          description: >-
            Whether Program has landed its own survey configuration upstream at
            least once.
        updated_at:
          type: string
          format: date-time
      required:
        - survey_id
        - platform
        - instructions
        - fine_tuning_template_id
        - config
        - initial_push_succeeded
        - updated_at
    SurveyListSummary:
      type:
        - object
        - 'null'
      properties:
        kind:
          type: string
          enum:
            - waiting_questionnaire
            - programming
            - migrated
        programming:
          type: object
          properties:
            run_id:
              type: string
              minLength: 1
            status:
              $ref: '#/components/schemas/SurveyListProgrammingStatus'
            waiting_on_target_selection:
              type: boolean
              description: >-
                True while programming is blocked on user input (configure /
                platform / template).
            started_at:
              type:
                - string
                - 'null'
              format: date-time
            completed_at:
              type:
                - string
                - 'null'
              format: date-time
            target_wait_ms:
              type: integer
              minimum: 0
              description: Finalized user-input wait already accrued (ms).
            target_wait_started_at:
              type:
                - string
                - 'null'
              format: date-time
              description: Set only while actively blocked on user input after compose.
          required:
            - run_id
            - status
            - waiting_on_target_selection
            - started_at
            - completed_at
            - target_wait_ms
            - target_wait_started_at
        migrated_from:
          type: object
          properties:
            survey_id:
              type: string
              format: uuid
            slug:
              type: string
              minLength: 1
            name:
              type: string
              minLength: 1
          required:
            - survey_id
            - slug
            - name
      required:
        - kind
    ProgrammingPlatform:
      type: string
      enum:
        - questra
        - decipher
        - confirmit
        - qualtrics
        - alchemer
    SurveyListProgrammingStatus:
      type: string
      enum:
        - pending
        - running
        - completed
        - failed
        - cancelled

````