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

# List test set versions

> List the prior-state version history for a test set, newest first. The live test set is the current version and is not included here. Each entry captures the test set's config and an ordered snapshot of its test-case rows.



## OpenAPI

````yaml /api-reference/v1/test-sets-v1.yaml get /test-sets/{test_set_id}/versions
openapi: 3.0.3
info:
  title: Test Sets API
  version: 1.0.0
  description: >
    API for managing test sets - collections of test cases for evaluation.


    Test sets organize test cases and can define parameters for test case
    generation.
  contact:
    name: Coval API Support
    url: https://coval.dev
    email: support@coval.dev
servers:
  - url: https://api.coval.dev/v1
    description: Production API
security:
  - apiKey: []
tags:
  - name: Test Sets
    description: Operations for managing test sets
paths:
  /test-sets/{test_set_id}/versions:
    get:
      tags:
        - Test Sets
      summary: List test set versions
      description: >-
        List the prior-state version history for a test set, newest first. The
        live test set is the current version and is not included here. Each
        entry captures the test set's config and an ordered snapshot of its
        test-case rows.
      operationId: listTestSetVersions
      parameters:
        - name: test_set_id
          in: path
          required: true
          description: Test set ID (8-character ID)
          schema:
            type: string
            minLength: 8
            maxLength: 8
          example: abc12345
      responses:
        '200':
          description: Successful response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ListTestSetVersionsResponse'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '404':
          $ref: '#/components/responses/NotFound'
        '500':
          $ref: '#/components/responses/InternalError'
components:
  schemas:
    ListTestSetVersionsResponse:
      type: object
      description: Response for GET /v1/test-sets/{test_set_id}/versions (newest first)
      required:
        - versions
      properties:
        versions:
          type: array
          items:
            $ref: '#/components/schemas/TestSetVersionResource'
    TestSetVersionResource:
      type: object
      description: >-
        A prior, displaced snapshot of a test set's content (config + test-case
        grid).
      required:
        - name
        - ulid
        - version_number
        - change_type
        - created_by
      properties:
        name:
          type: string
          description: Resource name
          example: test-sets/abc12345/versions/01KKWQYSF737ZN6X1Q1RYX8M2D
        ulid:
          type: string
          description: Version identifier (26-char ULID)
          example: 01KKWQYSF737ZN6X1Q1RYX8M2D
        version_number:
          type: integer
          description: Per-test-set monotonic version number, 1-based
          example: 2
        change_type:
          type: string
          description: >-
            How this version came about. A revert is a save whose new state
            mirrors an older version.
          enum:
            - save
            - revert
        label:
          type: string
          nullable: true
          description: Optional user-supplied tag
          example: v1.2 prod
        test_set_metadata:
          type: object
          additionalProperties: true
          description: Verbatim config snapshot
        parameters:
          type: object
          additionalProperties: true
          description: Verbatim parameter-sweep snapshot
        test_set_type:
          type: string
          nullable: true
        test_cases:
          type: array
          description: Ordered snapshot of the test set's active rows at this version
          items:
            type: object
            additionalProperties: true
        created_by:
          type: string
          description: Who created this version (user ULID)
        create_time:
          type: string
          format: date-time
          nullable: true
          description: When this version became current
    ErrorResponse:
      type: object
      description: Standard error response
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
            - details
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: INVALID_ARGUMENT
            message:
              type: string
              description: Human-readable error message
              example: Invalid request parameters
            details:
              type: array
              description: Detailed error information
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field that caused the error
                    example: slug
                  description:
                    type: string
                    description: Description of the error
                    example: slug already exists for this organization
  responses:
    Unauthorized:
      description: Authentication failed or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: UNAUTHENTICATED
              message: Authentication failed
              details:
                - field: X-API-Key
                  description: Invalid or missing API key
    NotFound:
      description: Resource not found or doesn't belong to organization
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: NOT_FOUND
              message: Test set not found
              details:
                - field: test_set_id
                  description: Test set 'abc12345' not found
    InternalError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          example:
            error:
              code: INTERNAL
              message: Internal server error
              details:
                - description: An unexpected error occurred while processing the request
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: X-API-Key
      description: Organization API key for authentication

````