---
title: "List label versions"
method: GET
path: "/v1/labels/{labelId}/versions"
tags: ["Labels"]
---

# List label versions

`GET /v1/labels/{labelId}/versions`

## Request

- Base URL: `https://gateway.app.clavata.ai:8443`
- URL: `https://gateway.app.clavata.ai:8443/v1/labels/{labelId}/versions`
- Auth: HTTP bearer
- TypeScript: <https://skmtc.dev/clavata/apis/clavata-public-api-v1/docs/v1/labels/:labelId/versions/get.ts> (a function with typed inputs; its response is checked against the schema)

Lists versions on a label in stable order: `sequential_version` ascending (oldest first), then version ID. Omitting `page_size` uses the default of 100. The maximum `page_size` is 1000. Negative `page_size` is rejected. A label with zero versions returns an empty list. Requires a label-first account; other accounts receive `FAILED_PRECONDITION`.

## Path parameters

- `labelId` string, required

## Query parameters

- `pageSize` integer
- `pageToken` string

## Response `200`

A successful response.

- V1ListLabelVersionsResponse
  - `labelVersions` V1LabelVersion[]
    - `labelVersionId` string
    - `labelId` string
    - `text` string
    - `blob` string, byte
    - `description` string
    - `signalCount` integer
    - `totalSignalTokens` integer
    - `created` string, date-time
    - `expunged` boolean
    - `createdById` string
    - `sequentialVersion` integer
    - `parentLabelVersionId` string
    - `complexityScore` number, float
    - `labelEvalOptions` V1LabelEvalOptions: LabelEvalOptions are options that can be set per-label to control evaluation behavior. Field numbers/types intentionally mirror PolicyEvalOptions for parity.
      - `bypassCache` boolean
      - `expedited` boolean
      - `bundleSize` integer
      - `threshold` number, double
      - `stack` string
      - `imageDetailLevel` 'IMAGE_DETAIL_LEVEL_UNSPECIFIED' | 'IMAGE_DETAIL_LEVEL_VERY_LOW' | 'IMAGE_DETAIL_LEVEL_LOW' | 'IMAGE_DETAIL_LEVEL_MEDIUM' | 'IMAGE_DETAIL_LEVEL_HIGH' | 'IMAGE_DETAIL_LEVEL_VERY_HIGH': ImageDetailLevel selects how much image detail is preserved when images are evaluated. Levels are semantic; the selected extractor's vision encoder maps each level to a model-specific token budget. Unspecified preserves the extractor's configured default.
    - `globalContext` string: Optional global context to inject into LLM context window during evaluation. This provides additional context about the nature of content being evaluated.
    - `tokenCountsV2` V1TokenCountsV2: TokenCountsV2 groups the static V2 token counts saved alongside a policy version, label version, or user label draft. The counts are calculated together, so message presence signals that V2 accounting is available for the saved DSL.
      - `dslTokenCount` integer: V2 DSL-only token count for display.
      - `globalContextTokens` integer: V2 token count for the saved global context.
      - `signalTokens` integer: V2 token count for formatted DSL signals.
      - `signalSpecialTokens` integer: V2 token count for DSL prompt special/structural tokens.
      - `contentSpecialTokens` integer: V2 token count for content prompt special/structural tokens.
  - `nextPageToken` string: Set when more versions remain after this page.

## Other responses

- `default`: An unexpected error response.

## Changes

- **2026-09-03** `703019caec67`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/clavata/apis/clavata-public-api-v1/changes/v1/labels/:labelId/versions/get.md)

---

[API](https://skmtc.dev/clavata/apis/clavata-public-api-v1.md) - [All operations](https://skmtc.dev/clavata/apis/clavata-public-api-v1/llms.txt) - [OpenAPI document](https://skmtc.dev/clavata/apis/clavata-public-api-v1/revisions/d7a854b0070f?raw)