---
title: "List evaluator versions"
method: GET
path: "/v2/evaluators/{evaluator_id}/versions"
tags: ["Evaluators"]
---

# List evaluator versions

`GET /v2/evaluators/{evaluator_id}/versions`

List all versions of an evaluator with cursor-based pagination.

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Path parameters

- `evaluator_id` string, required — A universally unique identifier (base64-encoded opaque string).

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

Returns a list of evaluator version objects

- ListEvaluatorVersionsResponse
  - `evaluator_versions` EvaluatorVersion[], required — A list of evaluator versions
    - union — A versioned snapshot of an evaluator's configuration. The `type` field discriminates the branch and matches the parent evaluator's `type`.
      - EvaluatorVersionTemplate — Evaluator version carrying a template (LLM) configuration.
        - `id` string, required — The unique identifier for this version
        - `evaluator_id` string, required — The parent evaluator ID
        - `commit_hash` string, required — A unique hash identifying this version
        - `commit_message` string, nullable, required — A message describing the changes in this version
        - `created_at` string, date-time, required — When this version was created
        - `created_by_user_id` string, nullable, required — The unique identifier for the user who created this version
        - `type` 'TEMPLATE', required — Discriminator identifying this as a template evaluator version. Always `TEMPLATE` for this variant.
        - `template_config` TemplateConfig, required
          - `name` string, required — Eval column name. Must match ^[a-zA-Z0-9_\s\-&()]+$
          - `template` string, required — The prompt template with variable placeholders
          - `include_explanations` boolean, required — Whether to include explanations in the evaluation output
          - `use_function_calling_if_available` boolean, required — Whether to use function calling if the model supports it
          - `use_structured_output` boolean — Whether to use structured output if the model supports it
          - `classification_choices` object, nullable — Map of choice label to numeric score (e.g. {"relevant": 1, "irrelevant": 0}). Null for legacy freeform evaluators that predate required choices.
          - `direction` 'MAXIMIZE' | 'MINIMIZE' | 'NONE' — The direction for optimization. Defaults to `NONE` when omitted. - MAXIMIZE: higher scores are better - MINIMIZE: lower scores are better - NONE: higher or lower scores are neither better nor worse
          - `data_granularity` 'SPAN' | 'TRACE' | 'SESSION' — Data granularity level for evaluation. - SPAN - Evaluate at the individual span level. - TRACE - Evaluate at the full trace level. - SESSION - Evaluate at the session level.
          - `llm_config` EvaluatorLlmConfig, required
            - `ai_integration_id` string, required — AI integration identifier (base64)
            - `model_name` string, required — Model name (e.g. gpt-4o)
            - `invocation_parameters` InvocationParams, required — Parameters for the LLM invocation
              - …
            - `provider_parameters` ProviderParams, required — Provider-specific parameters
              - …
      - EvaluatorVersionCode — Evaluator version carrying a code configuration.
        - `id` string, required — The unique identifier for this version
        - `evaluator_id` string, required — The parent evaluator ID
        - `commit_hash` string, required — A unique hash identifying this version
        - `commit_message` string, nullable, required — A message describing the changes in this version
        - `created_at` string, date-time, required — When this version was created
        - `created_by_user_id` string, nullable, required — The unique identifier for the user who created this version
        - `type` 'CODE', required — Discriminator identifying this as a code evaluator version. Always `CODE` for this variant.
        - `code_config` union, required — Discriminated union representing either a managed (built-in) or custom (user-supplied Python) code evaluator configuration, resolved by the nested `type` field (`MANAGED` -> `ManagedCodeConfig`, `CUSTOM` -> `CustomCodeConfig`). This inner `type` is independent of the parent evaluator version's `type` (which is always `CODE` here).
          - ManagedCodeConfig
            - `data_granularity` 'SPAN' | 'TRACE' | 'SESSION' — Data granularity level for evaluation. - SPAN - Evaluate at the individual span level. - TRACE - Evaluate at the full trace level. - SESSION - Evaluate at the session level.
            - `query_filter` string, nullable — Optional filter query over the chosen data granularity. When omitted or null, no filter is applied.
            - `type` 'MANAGED', required — Discriminator identifying this as a managed (built-in) code evaluator
            - `name` string, required — Eval column name. Must match ^[a-zA-Z0-9_\s\-&()]+$
            - `managed_evaluator` 'MATCHES_REGEX' | 'JSON_PARSEABLE' | 'CONTAINS_ANY_KEYWORD' | 'CONTAINS_ALL_KEYWORDS' | 'EXACT_MATCH', required — Built-in managed code evaluator name
            - `variables` string[], required — Dataset columns or span attributes passed into the evaluator (order and count must match the managed evaluator's requirements).
            - `static_params` StaticParam[] — Static parameters for the managed evaluator (see registry `args`). When omitted, the registry's required arguments must be satisfied by defaults on the evaluator class; otherwise validation fails with 400. If the registry has no args, omitting this field is equivalent to an empty list.
              - …
          - CustomCodeConfig
            - `data_granularity` 'SPAN' | 'TRACE' | 'SESSION' — Data granularity level for evaluation. - SPAN - Evaluate at the individual span level. - TRACE - Evaluate at the full trace level. - SESSION - Evaluate at the session level.
            - `query_filter` string, nullable — Optional filter query over the chosen data granularity. When omitted or null, no filter is applied.
            - `type` 'CUSTOM', required — Discriminator identifying this as a custom (user-supplied Python) code evaluator
            - `name` string, required — Eval column name. Must match ^[a-zA-Z0-9_\s\-&()]+$
            - `code` string, required — Python source defining the evaluator class
            - `imports` string, nullable — Optional package import block prepended when running the evaluator
            - `variables` string[], required — Dataset columns or span attributes mapped to evaluate() arguments
            - `static_params` StaticParam[] — Optional typed defaults accessible on the evaluator instance. Omit or pass an empty array when the custom class does not read any static parameters.
              - …
      - EvaluatorVersionHarness — Evaluator version backed by a harness evaluation config. Only common version metadata (id, commit info, timestamps) is returned — the harness configuration is not yet accessible and will be a future addition.
        - `id` string, required — The unique identifier for this version
        - `evaluator_id` string, required — The parent evaluator ID
        - `commit_hash` string, required — A unique hash identifying this version
        - `commit_message` string, nullable, required — A message describing the changes in this version
        - `created_at` string, date-time, required — When this version was created
        - `created_by_user_id` string, nullable, required — The unique identifier for the user who created this version
        - `type` 'HARNESS', required — Discriminator identifying this as a harness evaluator version.
      - EvaluatorVersionRemote — Evaluator version backed by a remote evaluation config. Only common version metadata (id, commit info, timestamps) is returned — the remote configuration is not yet accessible and will be a future addition.
        - `id` string, required — The unique identifier for this version
        - `evaluator_id` string, required — The parent evaluator ID
        - `commit_hash` string, required — A unique hash identifying this version
        - `commit_message` string, nullable, required — A message describing the changes in this version
        - `created_at` string, date-time, required — When this version was created
        - `created_by_user_id` string, nullable, required — The unique identifier for the user who created this version
        - `type` 'REMOTE', required — Discriminator identifying this as a remote evaluator version.
  - `pagination` PaginationMetadata, required — Cursor-based pagination metadata. Use `next_cursor` in the subsequent request's `cursor` query parameter.
    - `next_cursor` string — Opaque cursor for fetching the next page. Treat as an unreadable token. Present when `has_more` is true; omitted when `has_more` is false.
    - `has_more` boolean, required — True if another page of results is available.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `404` — Not found
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/1e87d8a4cf69/schema)