---
title: "List prompt versions"
method: GET
path: "/v2/prompts/{prompt_id}/versions"
tags: ["Prompts"]
---

# List prompt versions

`GET /v2/prompts/{prompt_id}/versions`

List all versions of a prompt, sorted by creation date with the most
recently created versions first.

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

## Path parameters

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

## Query parameters

- `limit` integer
- `cursor` string

## Response `200`

Returns a list of prompt version objects

- ListPromptVersionsResponse
  - `prompt_versions` PromptVersion[], required — A list of prompt versions
    - `id` string, required — The prompt version ID
    - `prompt_id` string, required — The prompt ID this version belongs to
    - `commit_hash` string, required — The commit hash of this version
    - `commit_message` string, required — The commit message describing the changes in this version
    - `messages` LLMMessage[], required — The messages that make up the prompt template
      - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
      - `content` string, nullable — The content of the message
      - `tool_call_id` string — The ID of the tool call this message is responding to
      - `tool_calls` ToolCall[] — Tool calls generated by the model
        - `id` string — The ID of the tool call
        - `type` 'FUNCTION', required — The type of tool call
        - `function` ToolCallFunction, required — The function to call
          - `name` string, required — The name of the function
          - `arguments` string, required — The arguments to the function as a JSON string
    - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE', required — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
    - `provider` 'OPEN_AI' | 'AZURE_OPEN_AI' | 'AWS_BEDROCK' | 'VERTEX_AI' | 'ANTHROPIC' | 'CUSTOM', required — The LLM provider to use
    - `model` string, required — The model to use for the call
    - `invocation_params` InvocationParams — Parameters for the LLM invocation
      - `temperature` number — Sampling temperature (higher = more random)
      - `max_tokens` integer — Maximum number of tokens to generate
      - `max_completion_tokens` integer — Maximum number of completion tokens to generate
      - `top_p` number — Nucleus sampling parameter
      - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
      - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
      - `stop` string[] — Stop sequences
      - `response_format` ResponseFormat — Response format configuration
        - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
        - `json_schema` JsonSchemaConfig — JSON schema configuration (when type is JSON_SCHEMA)
          - `name` string — The name of the JSON schema
          - `description` string — A description of the JSON schema
          - `schema` object — The JSON schema object
          - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
      - `tool_config` ToolConfig — Tool configuration for the LLM invocation
        - `tools` ToolDefinition[] — List of tool definitions available to the model
        - `tool_choice` unknown
      - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
      - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
      - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
      - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
      - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
    - `provider_params` ProviderParams — Provider-specific parameters
      - `azure_params` AzureParams — Azure OpenAI specific parameters
        - `azure_deployment_name` string — The Azure deployment name
        - `azure_openai_endpoint` string — The Azure OpenAI endpoint URL
        - `azure_openai_version` string — The Azure OpenAI API version
      - `anthropic_headers` AnthropicHeaders — Anthropic-specific headers
        - `anthropic_beta` string[], nullable — Anthropic beta feature flags
      - `anthropic_version` string — Anthropic API version
      - `bedrock_options` BedrockOptions — AWS Bedrock options
        - `use_converse_endpoint` boolean — Whether to use the AWS Bedrock Converse endpoint. Defaults to `false`.
      - `region` string — Region for the model deployment
    - `created_at` string, date-time, required — When the version was created
    - `created_by_user_id` string, required — The user ID of the user who created this version
    - `labels` string[] — Label names currently pointing to this version (e.g., "production", "staging"). Labels are case-sensitive.
  - `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/2ce448f1de13/schema)