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

# List Versions

> List saved versions for a Table sheet. Requests are scoped to the workspace associated with the API key; table, sheet, column, cell, operation, and version IDs must belong to that workspace.

List saved versions for a sheet using cursor pagination. Results are sorted by `version_number`; use `order=asc` or `order=desc` to control direction.

The response includes version summaries and related metadata in `data`. Pagination metadata is returned in `pagination`, including `next_cursor`, `has_more`, and `limit`.

Treat `next_cursor` as opaque. It includes the current sort, order, cursor value, and a hash of the active filters. Reuse a cursor only with the same `sort`, `order`, and filter parameters from the request that produced it; changing any of those while passing an old cursor returns an invalid cursor error.


## OpenAPI

````yaml GET /api/public/v2/tables/{table_id}/sheets/{sheet_id}/versions
openapi: 3.1.0
info:
  title: FastAPI
  version: 0.1.0
servers: []
security:
  - ApiKeyAuth: []
paths:
  /api/public/v2/tables/{table_id}/sheets/{sheet_id}/versions:
    get:
      tags:
        - tables
      summary: List Table Sheet Versions
      description: >-
        List saved versions for a Table sheet. Requests are scoped to the
        workspace associated with the API key; table, sheet, column, cell,
        operation, and version IDs must belong to that workspace.
      operationId: listTableSheetVersions
      parameters:
        - name: X-API-KEY
          in: header
          required: true
          schema:
            type: string
          description: >-
            Your PromptLayer API key. The key's workspace scopes table resources
            for this request.
        - name: table_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Table ID.
        - name: sheet_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
          description: Table sheet ID.
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: >-
            Cursor returned from the previous page. Public table cursors encode
            the current sort, order, cursor value, and a hash of the active
            filters; reuse the cursor with the same sort, order, and filter
            parameters from the previous request.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            default: 20
            minimum: 1
            maximum: 100
          description: Number of versions to return.
        - name: sort
          in: query
          required: false
          schema:
            type: string
            enum:
              - version_number
            default: version_number
          description: Sort field. Currently supports version_number.
        - name: order
          in: query
          required: false
          schema:
            type: string
            enum:
              - asc
              - desc
            default: desc
          description: Sort order.
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTableSheetVersionsResponse'
        '400':
          description: >-
            Invalid cursor, query parameter, sort/order, filter set, or
            workspace context.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Table or sheet not found.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
components:
  schemas:
    ListTableSheetVersionsResponse:
      type: object
      title: ListTableSheetVersionsResponse
      required:
        - success
        - data
        - pagination
        - filters
        - count
      properties:
        success:
          type: boolean
        data:
          type: array
          items:
            $ref: '#/components/schemas/TableSheetVersion'
          description: Items returned on this page.
        pagination:
          $ref: '#/components/schemas/PublicListPagination'
        filters:
          $ref: '#/components/schemas/EmptyPublicFilters'
          description: >-
            Filters applied to this page. The cursor includes a hash of this
            filter set, so changing filters while reusing a cursor returns an
            invalid cursor error.
        count:
          type: integer
          description: Number of items returned on this page.
      additionalProperties: false
    ErrorResponse:
      type: object
      properties:
        success:
          type: boolean
          default: false
          description: Indicates that the request failed.
        message:
          type: string
          description: Human-readable error message.
        error:
          type: string
          description: Machine-readable or fallback error message.
      additionalProperties: true
      description: >-
        Standard error response. Some legacy endpoints may return either message
        or error.
    TableSheetVersion:
      type: object
      title: TableSheetVersion
      required:
        - id
        - sheet_id
        - version_number
      properties:
        id:
          type: string
          format: uuid
        sheet_id:
          type: string
          format: uuid
        version_number:
          type: integer
          description: Sequential saved version number for this sheet.
        name:
          type: string
          nullable: true
        created_by:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
          nullable: true
        metadata:
          additionalProperties: true
          type: object
        deltas:
          type: array
          items:
            additionalProperties: true
            type: object
        snapshot:
          additionalProperties: true
          type: object
        score:
          additionalProperties: true
          type: object
        score_configuration:
          type: object
          nullable: true
          additionalProperties: true
      additionalProperties: true
    PublicListPagination:
      type: object
      title: PublicListPagination
      required:
        - next_cursor
        - prev_cursor
        - has_more
        - limit
      properties:
        next_cursor:
          type: string
          nullable: true
          description: >-
            Opaque cursor to pass as cursor for the next page, or null when
            there is no next page. The cursor is valid only with the same sort,
            order, and filter parameters used to produce it.
        prev_cursor:
          type: string
          nullable: true
          description: >-
            Reserved for previous-page cursors. Public table list endpoints
            currently return null.
        has_more:
          type: boolean
          description: Whether another page is available.
        limit:
          type: integer
          description: Requested page size.
      additionalProperties: false
      description: >-
        Cursor pagination metadata for public table list endpoints. Cursors are
        opaque and include the active sort, order, cursor value, and a hash of
        the active filter set.
    EmptyPublicFilters:
      type: object
      title: EmptyPublicFilters
      description: This endpoint does not echo any filter fields.
      maxProperties: 0
      additionalProperties: false
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: X-API-KEY

````