---
title: "List deployment versions"
method: GET
path: "/v2/deployments/{keyOrID}/versions"
tags: ["Deployments"]
---

# List deployment versions

`GET /v2/deployments/{keyOrID}/versions`

## Request

- Base URL: `https://my.orq.ai`
- URL: `https://my.orq.ai/v2/deployments/{keyOrID}/versions`
- Auth: HTTP bearer

List saved versions across deployment variants, including drafts, newest first. Resolve the deployment by key or ID. Optionally filter by variant_id. Use the version _id with starting_after or ending_before to paginate.

## Path parameters

- `keyOrID` string, required: Deployment key or ID.

## Query parameters

- `limit` integer: A limit on the number of objects to be returned. Limit can range between 1 and 50, and the default is 10
- `starting_after` string, ulid: Version _id after which to fetch the next page.
- `ending_before` string, ulid: Version _id before which to fetch the previous page.
- `variant_id` string, uuid: Return versions of this variant only.

## Response `200`

Deployment versions retrieved.

- object
  - `object` 'list', required
  - `data` object[], required
    - `_id` string, ulid, required: The id of the resource
    - `deployment_id` string, required
    - `variant_id` string, required
    - `prompt_config` object, required
      - `model` string, required
      - `model_db_id` string, required
      - `model_type` 'chat' | 'completion' | 'embedding' | 'image' | 'tts' | 'stt' | 'rerank' | 'ocr' | 'moderation' | 'classify' | 'vision', required: The modality of the model
      - `model_parameters` object, required: Model Parameters: Not all parameters apply to every model
        - `temperature` number: Only supported on `chat` and `completion` models.
        - `maxTokens` number: Only supported on `chat` and `completion` models.
        - `topK` number: Only supported on `chat` and `completion` models.
        - `topP` number: Only supported on `chat` and `completion` models.
        - `frequencyPenalty` number: Only supported on `chat` and `completion` models.
        - `presencePenalty` number: Only supported on `chat` and `completion` models.
        - `numImages` number: Only supported on `image` models.
        - `seed` number: Best effort deterministic seed for the model. Currently only OpenAI models support these
        - `format` 'url' | 'b64_json' | 'text' | 'json_object': Only supported on `image` models.
        - `dimensions` string: Only supported on `image` models.
        - `quality` string: Only supported on `image` models.
        - `style` string: Only supported on `image` models.
        - `responseFormat` union: An object specifying the format that the model must output. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
          - object
            - `type` 'json_schema', required
            - `display_name` string
            - `json_schema` object, required
              - …
          - object
            - `type` 'json_object', required
          - object
            - `type` 'text', required
          - 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'
          - 'url' | 'base64_json'
          - 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
        - `cacheControl` object, nullable: Provider-level prompt caching configuration applied to the request. Creates a cache control breakpoint covering the request content. Only supported by `Anthropic` Claude models.
          - `type` 'ephemeral', required: Create a cache control breakpoint. Accepts only the value "ephemeral".
          - `ttl` '5m' | '1h': The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by `Anthropic` Claude models.
        - `photoRealVersion` 'v1' | 'v2': The version of photoReal to use. Must be v1 or v2. Only available for `leonardoai` provider
        - `encoding_format` 'float' | 'base64': The format to return the embeddings
        - `reasoningEffort` 'none' | 'disable' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
        - `budgetTokens` number: Gives the model enhanced reasoning capabilities for complex tasks. A value of 0 disables thinking. The minimum budget tokens for thinking are 1024. The Budget Tokens should never exceed the Max Tokens parameter. Only supported by `Anthropic`
        - `verbosity` 'low' | 'medium' | 'high': Controls the verbosity of the model output.
        - `thinkingLevel` 'minimal' | 'low' | 'medium' | 'high': The level of thinking to use for the model. Only supported by `Google AI`
      - `provider` 'openai' | 'groq' | 'cohere' | 'azure' | 'aws' | 'google' | 'google-ai' | 'huggingface' | 'togetherai' | 'perplexity' | 'anthropic' | 'leonardoai' | 'fal' | 'nvidia' | 'jina' | 'elevenlabs' | 'litellm' | 'cerebras' | 'openailike' | 'bytedance' | 'mistral' | 'deepseek' | 'moonshotai' | 'zai' | 'minimax' | 'xai' | 'alibaba' | 'tensorix' | 'scaleway' | 'hcompany' | 'inception' | 'particle' | 'munito' | 'inceptron' | 'wafer' | 'poolside' | 'tencent' | 'nebius' | 'fireworks' | 'baseten' | 'reson8' | 'meta' | 'greenpt' | 'liquid' | 'typesafe' | 'berget' | 'cloudflare' | 'slack' | 'orq', required
      - `messages` object[], required
        - `role` 'system' | 'developer' | 'assistant' | 'user' | 'exception' | 'tool' | 'prompt' | 'correction' | 'expected_output', required: The role of the prompt message
        - `content` union, required: The contents of the user message. Either the text content of the message or an array of content parts with a defined type, each can be of type `text` or `image_url` when passing in images. You can pass multiple images by adding multiple `image_url` content parts. Can be null for tool messages in certain scenarios.
          - string
          - union[]
            - union
              - …
        - `tool_calls` object[]
          - `id` string
          - `index` number
          - `type` 'function', required
          - `function` object, required
            - `name` string, required
            - `arguments` string, required: JSON string arguments for the functions
        - `tool_call_id` string, nullable
        - `id` string, ulid: The id of the resource
      - `integration_id` union: The ID of the integration to use
        - string
        - string, ulid: The id of the resource
      - `version` string
    - `fallbacks` object[], required
      - `model` string, required
      - `model_db_id` string, required
      - `model_type` 'chat' | 'completion' | 'embedding' | 'image' | 'tts' | 'stt' | 'rerank' | 'ocr' | 'moderation' | 'classify' | 'vision', required: The modality of the model
      - `model_parameters` object, required: Model Parameters: Not all parameters apply to every model
        - `temperature` number: Only supported on `chat` and `completion` models.
        - `maxTokens` number: Only supported on `chat` and `completion` models.
        - `topK` number: Only supported on `chat` and `completion` models.
        - `topP` number: Only supported on `chat` and `completion` models.
        - `frequencyPenalty` number: Only supported on `chat` and `completion` models.
        - `presencePenalty` number: Only supported on `chat` and `completion` models.
        - `numImages` number: Only supported on `image` models.
        - `seed` number: Best effort deterministic seed for the model. Currently only OpenAI models support these
        - `format` 'url' | 'b64_json' | 'text' | 'json_object': Only supported on `image` models.
        - `dimensions` string: Only supported on `image` models.
        - `quality` string: Only supported on `image` models.
        - `style` string: Only supported on `image` models.
        - `responseFormat` union: An object specifying the format that the model must output. Setting to `{ "type": "json_schema", "json_schema": {...} }` enables Structured Outputs which ensures the model will match your supplied JSON schema Setting to `{ "type": "json_object" }` enables JSON mode, which ensures the message the model generates is valid JSON. Important: when using JSON mode, you must also instruct the model to produce JSON yourself via a system or user message. Without this, the model may generate an unending stream of whitespace until the generation reaches the token limit, resulting in a long-running and seemingly "stuck" request. Also note that the message content may be partially cut off if finish_reason="length", which indicates the generation exceeded max_tokens or the conversation exceeded the max context length.
          - object
            - `type` 'json_schema', required
            - `display_name` string
            - `json_schema` object, required
              - …
          - object
            - `type` 'json_object', required
          - object
            - `type` 'text', required
          - 'mp3' | 'opus' | 'aac' | 'flac' | 'wav' | 'pcm'
          - 'url' | 'base64_json'
          - 'json' | 'text' | 'srt' | 'verbose_json' | 'vtt'
        - `cacheControl` object, nullable: Provider-level prompt caching configuration applied to the request. Creates a cache control breakpoint covering the request content. Only supported by `Anthropic` Claude models.
          - `type` 'ephemeral', required: Create a cache control breakpoint. Accepts only the value "ephemeral".
          - `ttl` '5m' | '1h': The time-to-live for the cache control breakpoint. This may be one of the following values: - `5m`: 5 minutes - `1h`: 1 hour Defaults to `5m`. Only supported by `Anthropic` Claude models.
        - `photoRealVersion` 'v1' | 'v2': The version of photoReal to use. Must be v1 or v2. Only available for `leonardoai` provider
        - `encoding_format` 'float' | 'base64': The format to return the embeddings
        - `reasoningEffort` 'none' | 'disable' | 'minimal' | 'low' | 'medium' | 'high' | 'xhigh' | 'max': Constrains effort on reasoning for reasoning models. Reducing reasoning effort can result in faster responses and fewer tokens used on reasoning in a response.
        - `budgetTokens` number: Gives the model enhanced reasoning capabilities for complex tasks. A value of 0 disables thinking. The minimum budget tokens for thinking are 1024. The Budget Tokens should never exceed the Max Tokens parameter. Only supported by `Anthropic`
        - `verbosity` 'low' | 'medium' | 'high': Controls the verbosity of the model output.
        - `thinkingLevel` 'minimal' | 'low' | 'medium' | 'high': The level of thinking to use for the model. Only supported by `Google AI`
      - `provider` 'openai' | 'groq' | 'cohere' | 'azure' | 'aws' | 'google' | 'google-ai' | 'huggingface' | 'togetherai' | 'perplexity' | 'anthropic' | 'leonardoai' | 'fal' | 'nvidia' | 'jina' | 'elevenlabs' | 'litellm' | 'cerebras' | 'openailike' | 'bytedance' | 'mistral' | 'deepseek' | 'moonshotai' | 'zai' | 'minimax' | 'xai' | 'alibaba' | 'tensorix' | 'scaleway' | 'hcompany' | 'inception' | 'particle' | 'munito' | 'inceptron' | 'wafer' | 'poolside' | 'tencent' | 'nebius' | 'fireworks' | 'baseten' | 'reson8' | 'meta' | 'greenpt' | 'liquid' | 'typesafe' | 'berget' | 'cloudflare' | 'slack' | 'orq', required
      - `integration_id` union: The ID of the integration to use
        - string
        - string, ulid: The id of the resource
      - `version` string
    - `tools` object[], required
      - `display_name` string
      - `type` 'function', required: The type of the tool. Currently, only `function` is supported.
      - `function` object, required
        - `name` string, required: The name of the function to be called. Must be a-z, A-Z, 0-9, or contain underscores and dashes, with a maximum length of 64.
        - `description` string: A description of what the function does, used by the model to choose when and how to call the function.
        - `strict` boolean
        - `parameters` object, required: The parameters the functions accepts, described as a JSON Schema object. Omitting `parameters` defines a function with an empty parameter list.
          - `type` 'object', required
          - `properties` object, required
          - `required` string[]
          - `additionalProperties` false
      - `id` number
    - `variables` object[], required
      - `key` string, required
      - `value` unknown
      - `is_pii` boolean
      - `description` string
    - `notes` string
    - `timestamp` string, date-time, required
    - `retry_count` number
    - `version` string, required
    - `description` string, required
    - `status` 'live' | 'draft' | 'pending' | 'published', required
    - `user_id` string, nullable, required
    - `knowledge_bases` object[]
      - `id` string, ulid: The unique identifier of the playground knowledge base
      - `knowledge_id` string, ulid, required: The linked Knowledge ID
      - `configuration` union, required: Defines the configuration settings which can either be for a user message or a text entry.
        - object: Defines the configuration settings for a last user message type retrieval.
          - `type` 'last_user_message', required
        - object: Defines the configuration settings for a static query.
          - `type` 'query', required
          - `query` string, required
    - `settings` object
      - `guardrails` object[]
        - `id` string, required: Unique key or identifier of the evaluator
        - `sample_rate` number: The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
        - `execute_on` 'input' | 'output' | 'both', required: Determines whether the evaluator runs on the agent input (user message) or output (agent response).
      - `evaluators` object[]
        - `id` string, required: Unique key or identifier of the evaluator
        - `sample_rate` number: The percentage of executions to evaluate with this evaluator (1-100). For example, a value of 50 means the evaluator will run on approximately half of the executions.
        - `execute_on` 'input' | 'output' | 'both', required: Determines whether the evaluator runs on the agent input (user message) or output (agent response).
      - `cache` union
        - object
          - `enabled` false, required
        - object
          - `enabled` true, required
          - `type` 'exact' | 'semantic', required
          - `ttl` number, required
      - `guardrailBehaviour` 'none' | 'retry' | 'fallback'
      - `engine` 'text' | 'jinja' | 'mustache'
      - `input_masking` boolean
      - `system_masking` boolean
      - `output_masking` boolean
  - `has_more` boolean, required

## Other responses

- `400`: Invalid query parameters.
- `401`: Authentication required.
- `403`: Insufficient deployment permissions.
- `404`: Deployment not found or inaccessible.

## Changes

> 554 revisions in range; 71 not diffed.

- **2026-10-29** `928a71e92252`: 4 warning, 1 info
  - added the new `munito` enum value to the `data/items/fallbacks/items/provider` response property for the response status `200`
  - added the new `munito` enum value to the `data/items/prompt_config/provider` response property for the response status `200`
  - added the new `particle` enum value to the `data/items/fallbacks/items/provider` response property for the response status `200`
  - added the new `particle` enum value to the `data/items/prompt_config/provider` response property for the response status `200`
  - …1 more
- **2026-10-29** `33d63277cd4e`: 5 info
  - the `id` response's property default value changed from `01M63PG4VW384Q1DN3PKNP4CJ4` to `01M640RME986JGHM1WAXX066VX` for the status `200`
  - removed the `munito` enum value from the `data/items/fallbacks/items/provider` response property for the response status `200`
  - removed the `munito` enum value from the `data/items/prompt_config/provider` response property for the response status `200`
  - removed the `particle` enum value from the `data/items/fallbacks/items/provider` response property for the response status `200`
  - …1 more
- **2026-10-29** `d8d7c10a8a0c`: 1 info
  - the `id` response's property default value changed from `01M63KY6Y49K4P2F491624AS89` to `01M63PG4VW384Q1DN3PKNP4CJ4` for the status `200`
- …earlier changes not shown

[Operation history](https://skmtc.dev/orq-ai/apis/orq-ai-api/changes/v2/deployments/:keyOrID/versions/get.md)

---

[API](https://skmtc.dev/orq-ai/apis/orq-ai-api.md) - [All operations](https://skmtc.dev/orq-ai/apis/orq-ai-api/llms.txt) - [OpenAPI document](https://skmtc.dev/orq-ai/apis/orq-ai-api/revisions/928a71e92252?raw)