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

# Get a label

`GET /v1/labels/{labelId}`

## Request

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

Returns a label owned by the authenticated account, including a page of its versions ordered by sequential version number ascending (oldest first), then version ID. When more versions remain, `next_page_token` is set; pass it to `GET /v1/labels/{labelId}/versions` to continue. Cross-account IDs return NOT_FOUND. Requires a label-first account; other accounts receive `FAILED_PRECONDITION`.

## Path parameters

- `labelId` string, required

## Response `200`

A successful response.

- V1GetLabelResponse
  - `label` Sharedv1Label: Label is a first-class, referenceable label entity (V2). Labels can be policy-scoped (policy_id set) or independent (policy_id empty). Policy-scoped labels are uniquely identified by (customer_id, name, policy_id). Independent labels are uniquely identified by (customer_id, name).
    - `labelId` string
    - `name` string
    - `customerId` string
    - `policyId` string
    - `disabled` boolean
    - `created` string, date-time
    - `updated` string, date-time
    - `expunged` boolean
    - `description` string
    - `archivedAt` string, date-time
    - `tags` V1LabelTag[]
      - `labelTagId` string
      - `customerId` string
      - `name` string
      - `color` string
      - `created` string, date-time
      - `updated` string, date-time
      - `expunged` boolean
    - `importProvenance` V1LabelImportProvenance: LabelImportProvenance records where a label's library-derived lineage began. Set on labels created via LabelLibraryService.ImportLibraryLabel and preserved on clones derived from them.
      - `libraryLabelId` string: Opaque source library catalog id (library_labels.id).
      - `libraryVersionId` string: The library label version id that was imported (the pinned published version).
      - `libraryName` string: The library entry's display name at import time (denormalized for stable display).
      - `importedAt` string, date-time: When the original import happened.
  - `labelVersions` V1LabelVersion[]: Versions on this label, ordered by sequential_version ascending (oldest first), then version ID. This is a bounded page (default 100, max 1000). When more versions remain, next_page_token is set; continue with ListLabelVersions using that token.
    - `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

## 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/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)