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

# List poll options

> Returns one page of options. The options have a hierarchy with varying levels.
                   API calls can navigate through this hierarchy by passing a parent_option_id.
                   The default page size depends on the poll type and the poll's options_per_page setting; use the X-Total-Pages / X-Total-Count response headers to page through the full list.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/polls/{poll_id}/options
openapi: 3.0.1
info:
  title: PollUnit API
  version: v1
  description: Programmatic access to PollUnit.
servers:
  - url: https://pollunit.com
    description: Production
  - url: http://localhost:3000
    description: Development
security:
  - bearerAuth: []
paths:
  /api/v1/polls/{poll_id}/options:
    parameters:
      - name: poll_id
        in: path
        description: Poll member_hash or admin_hash
        required: true
        schema:
          type: string
      - name: organization_id
        in: query
        required: false
        description: >-
          public_id of an organization the user belongs to. When given, the
          request runs in that organization context instead of the personal
          account.
        schema:
          type: string
    get:
      tags:
        - Options
      summary: List poll options
      description: >-
        Returns one page of options. The options have a hierarchy with varying
        levels.
                           API calls can navigate through this hierarchy by passing a parent_option_id.
                           The default page size depends on the poll type and the poll's options_per_page setting; use the X-Total-Pages / X-Total-Count response headers to page through the full list.
      parameters:
        - name: parent_option_id
          in: query
          required: false
          description: Public ID of parent option id, to list its child options.
          schema:
            type: string
        - name: page
          in: query
          required: false
          description: Page to return, 1-based. Defaults to 1.
          schema:
            type: integer
        - name: per
          in: query
          required: false
          description: >-
            Options per page. Defaults to the page size of the poll type. At
            most 100.
          schema:
            type: integer
      responses:
        '200':
          description: options listed
          headers:
            X-Page:
              schema:
                type: integer
              description: Current page, 1-based
            X-Per-Page:
              schema:
                type: integer
              description: Options per page
            X-Total-Pages:
              schema:
                type: integer
              description: Number of pages
            X-Total-Count:
              schema:
                type: integer
              description: Total number of options matching the request
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/OptionListItem'
        '401':
          description: unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Unauthorized'
        '404':
          description: poll not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFound'
      security:
        - bearerAuth: []
components:
  schemas:
    OptionListItem:
      type: object
      description: >-
        Summary of a poll option as returned by the list endpoint. Fields are
        included conditionally depending on the poll's visibility settings and
        your access level (admin vs. member).
      properties:
        id:
          type: string
          description: Option public_id
        admin_url:
          type: string
          format: uri
          nullable: true
          description: Admin access only
        public_url:
          type: string
          format: uri
        parent_option_id:
          type: string
          nullable: true
        type:
          type: string
          description: Option STI class
          example: Options::TextOption
        child_option_type:
          type: string
          nullable: true
        content:
          type: string
          nullable: true
        subtitle:
          type: string
          nullable: true
        author_name:
          type: string
          nullable: true
        position:
          type: integer
          nullable: true
        state:
          type: string
          nullable: true
          enum:
            - incoming
            - investigation
            - planned
            - in_implementation
            - rejected
            - done
          description: Collection polls only
        rank:
          type: integer
          nullable: true
        rating:
          type: number
          format: float
          nullable: true
        average_rating:
          type: number
          format: float
          nullable: true
        best_rating:
          type: boolean
          nullable: true
        selected:
          type: boolean
          nullable: true
        paid:
          type: boolean
          nullable: true
        info_link:
          type: string
          nullable: true
        info_link_title:
          type: string
          nullable: true
        start_date:
          type: string
          format: date-time
          nullable: true
        end_date:
          type: string
          format: date-time
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        updated_at:
          type: string
          format: date-time
          nullable: true
        approval_state:
          type: string
          nullable: true
          description: Admin access only
          enum:
            - unreviewed
            - approved
            - disapproved
        approval_state_updated_at:
          type: string
          format: date-time
          nullable: true
          description: Admin access only
        archived:
          type: boolean
          nullable: true
          description: Admin access only
        attachment:
          $ref: '#/components/schemas/OptionAttachment'
      required:
        - id
        - type
        - public_url
    Unauthorized:
      type: object
      properties:
        error:
          type: string
          example: Unauthorized
    NotFound:
      type: object
      properties:
        error:
          type: string
          example: Not Found
    OptionAttachment:
      type: object
      nullable: true
      description: >-
        URLs of the file uploaded to the option, returned by both the list and
        the show endpoint. Only present for option types that carry an uploaded
        file (image, photo, audio, drawing and advent calendar options);
        youtube/vimeo and uploaded-video options do not have it. The
        `attachment_url_*` keys are the processed derivatives that exist for
        this file, so which ones are returned depends on the uploaded file:
        images and videos get `large`, `thumb` and `social`, an audio file only
        gets `cover` if it has embedded cover art, and a file that is still
        processing has none at all. The whole object is omitted when none of its
        keys apply, e.g. an option without a file or a still-processing upload
        you have no download access to.
      properties:
        attachment_url_large:
          type: string
          format: uri
          nullable: true
          description: Long edge resized to 1920px (webp).
        attachment_url_thumb:
          type: string
          format: uri
          nullable: true
          description: Width resized to 496px (webp).
        attachment_url_social:
          type: string
          format: uri
          nullable: true
          description: Long edge resized to 1200px (jpg), used for social media previews.
        attachment_url_cover:
          type: string
          format: uri
          nullable: true
          description: Cover art extracted from an audio file.
        attachment_original_url:
          type: string
          format: uri
          nullable: true
          description: >-
            The file as it was uploaded. Admin access only. For images and
            videos this falls back to the `large` derivative unless the account
            keeps source files.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: opaque
      description: Personal API token — find yours under My Account → API.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.