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

# Read one dataset version and a page of its test cases

> Read an immutable snapshot: the version plus its cases, whole or a page at a time.

Paging is opt-in through `limit`, because the released SDKs pull a version with one
request and never follow `next_cursor`; a default page would silently truncate them.
A version's case set is unbounded in practice, so any other caller should page.
`input`/`expected` come back as native JSON values.



## OpenAPI

````yaml /api-reference/openapi.json get /api/v1/public/dataset-versions/{version_id}
openapi: 3.1.0
info:
  title: TraceRoot Public API
  version: 0.1.0
servers:
  - description: TraceRoot Cloud
    url: https://app.traceroot.ai
  - description: Self-hosted
    url: '{baseUrl}'
    variables:
      baseUrl:
        default: http://localhost:8000
        description: Your TraceRoot backend URL
security: []
paths:
  /api/v1/public/dataset-versions/{version_id}:
    get:
      tags:
        - Offline Eval
      summary: Read one dataset version and a page of its test cases
      description: >-
        Read an immutable snapshot: the version plus its cases, whole or a page
        at a time.


        Paging is opt-in through `limit`, because the released SDKs pull a
        version with one

        request and never follow `next_cursor`; a default page would silently
        truncate them.

        A version's case set is unbounded in practice, so any other caller
        should page.

        `input`/`expected` come back as native JSON values.
      operationId: get_dataset_version
      parameters:
        - in: path
          name: version_id
          required: true
          schema:
            title: Version Id
            type: string
        - description: >-
            Test cases per page. Omit it, with no cursor, to receive the whole
            version in one response, as an SDK pulling the snapshot it will run
            does; pass it to page.
          in: query
          name: limit
          required: false
          schema:
            anyOf:
              - maximum: 1000
                minimum: 1
                type: integer
              - type: 'null'
            description: >-
              Test cases per page. Omit it, with no cursor, to receive the whole
              version in one response, as an SDK pulling the snapshot it will
              run does; pass it to page.
            title: Limit
        - description: Opaque cursor from a previous page
          in: query
          name: cursor
          required: false
          schema:
            anyOf:
              - maxLength: 64
                minLength: 1
                type: string
              - type: 'null'
            description: Opaque cursor from a previous page
            title: Cursor
        - description: >-
            Target project for the request. Required when authenticating with a
            user session token (a user credential is only meaningful scoped to a
            project); for an API key it is optional and, if given, must match
            the key's project.
          in: query
          name: project_id
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Target project for the request. Required when authenticating with
              a user session token (a user credential is only meaningful scoped
              to a project); for an API key it is optional and, if given, must
              match the key's project.
            title: Project Id
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/GetDatasetVersionResponse'
          description: Successful Response
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Invalid request
        '401':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication failed
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: No access to this project
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Not found
        '422':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Validation error
        '429':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Rate limit exceeded
        '503':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
          description: Authentication service unavailable
      security:
        - BearerAuth: []
components:
  schemas:
    GetDatasetVersionResponse:
      description: 'A version snapshot: the version''s identity plus a PAGE of its cases.'
      properties:
        dataset_id:
          title: Dataset Id
          type: string
        dataset_version_id:
          title: Dataset Version Id
          type: string
        items:
          items:
            $ref: '#/components/schemas/PublicTestCase'
          title: Items
          type: array
        label:
          anyOf:
            - type: string
            - type: 'null'
          title: Label
        next_cursor:
          anyOf:
            - type: string
            - type: 'null'
          title: Next Cursor
        version_number:
          title: Version Number
          type: integer
      required:
        - dataset_version_id
        - dataset_id
        - version_number
        - label
        - items
        - next_cursor
      title: GetDatasetVersionResponse
      type: object
    ErrorResponse:
      description: >-
        The canonical public error envelope (matches the gateway's normalized
        shape).
      properties:
        detail:
          title: Detail
          type: string
      required:
        - detail
      title: ErrorResponse
      type: object
    PublicTestCase:
      description: >-
        One test case in a version snapshot.


        ``input``/``expected``/``metadata`` are NATIVE JSON values — an object
        stays an

        object, a JSON-looking string stays a string — so they are ``Any``, not
        ``str``.
      properties:
        expected:
          title: Expected
        input:
          title: Input
        metadata:
          title: Metadata
        source_span_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Span Id
        source_trace_id:
          anyOf:
            - type: string
            - type: 'null'
          title: Source Trace Id
        test_case_id:
          title: Test Case Id
          type: string
      required:
        - test_case_id
        - input
        - expected
        - metadata
        - source_trace_id
        - source_span_id
      title: PublicTestCase
      type: object
  securitySchemes:
    BearerAuth:
      scheme: bearer
      type: http

````

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