Implementation:Arize ai Phoenix Prompts Get

Knowledge Sources	Phoenix
Domains	Prompt Engineering, Runtime Configuration, Python API
Last Updated	2026-02-14 00:00 GMT

Overview

Concrete tool for retrieving versioned prompt configurations at runtime provided by the arize-phoenix-client Python package.

Description

The Prompts.get() method fetches a specific prompt version from the Phoenix server based on one of three resolution strategies: by version ID, by prompt name and tag, or by prompt name alone (latest). The method returns a fully populated PromptVersion object containing the template, model configuration, invocation parameters, tools, response format, and the server-assigned version ID.

The resolution logic follows a strict priority order:

1. If prompt_version_id is provided, it takes precedence and the method performs a direct version lookup.
2. If prompt_identifier and tag are both provided, the method looks up the version currently pointed to by the named tag.
3. If only prompt_identifier is provided, the method returns the latest (most recently created) version.

This priority order is enforced by an internal URL construction helper that maps parameters to the appropriate API endpoint.

Usage

Use Prompts.get() when:

• Fetching the production-tagged prompt at application startup or per-request.
• Retrieving a specific version by ID for evaluation, debugging, or audit purposes.
• Loading the latest version during development and experimentation.
• Implementing environment-specific prompt resolution using tags.

Code Reference

Source Location

• Repository: Phoenix
• File: packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py (lines 76-124)
• URL construction helper: _url() function (lines 569-619 in the same file)

Signature

def get(
    self,
    *,
    prompt_version_id: Optional[str] = None,
    prompt_identifier: Optional[str] = None,
    tag: Optional[str] = None,
) -> PromptVersion

Import

from phoenix.client import Client

client = Client()
prompt_version = client.prompts.get(prompt_identifier="my-prompt")

I/O Contract

Inputs

Name	Type	Required	Description
prompt_version_id	Optional[str]	No	The unique identifier for a specific prompt version. When provided, this takes precedence over all other parameters and performs a direct version lookup.
prompt_identifier	Optional[str]	No	The name or identifier of the prompt. Required if prompt_version_id is not provided. Used in combination with tag for tagged lookup or alone for latest version lookup.
tag	Optional[str]	No	An optional tag name (e.g., "production", "staging") to filter the prompt version. Only used in combination with prompt_identifier. Ignored if prompt_version_id is provided.

Note: At least one of prompt_version_id or prompt_identifier must be provided. An AssertionError is raised if neither is specified.

Outputs

Name	Type	Description
return value	PromptVersion	The retrieved prompt version object. Contains the full prompt configuration including template messages, model name, model provider, template format, invocation parameters, tools, response format, description, and the server-assigned version id.

Resolution Strategies

Strategy	Parameters	API Endpoint	Use Case
Direct version lookup	prompt_version_id="abc-123"	GET v1/prompt_versions/abc-123	Reproducible evaluation, debugging, audit
Tagged version lookup	prompt_identifier="my-prompt", tag="production"	GET v1/prompts/my-prompt/tags/production	Production serving, environment-specific config
Latest version lookup	prompt_identifier="my-prompt"	GET v1/prompts/my-prompt/latest	Development, rapid iteration

Usage Examples

Retrieve the Latest Version

from phoenix.client import Client

client = Client()

# Get the most recently created version of the prompt
prompt_version = client.prompts.get(prompt_identifier="text-summarizer")

print(f"Version ID: {prompt_version.id}")

Retrieve a Production-Tagged Version

from phoenix.client import Client

client = Client()

# Get the version currently tagged as "production"
prompt_version = client.prompts.get(
    prompt_identifier="text-summarizer",
    tag="production",
)

print(f"Production version ID: {prompt_version.id}")

Retrieve a Specific Version by ID

from phoenix.client import Client

client = Client()

# Get an exact version for reproducible evaluation
prompt_version = client.prompts.get(prompt_version_id="abc-123-def-456")

print(f"Version ID: {prompt_version.id}")

Retrieve and Use with an LLM SDK

from phoenix.client import Client

client = Client()

# Retrieve the production prompt
prompt_version = client.prompts.get(
    prompt_identifier="qa-assistant",
    tag="production",
)

# Format it for OpenAI and call the API
formatted = prompt_version.format(
    variables={"question": "What is the capital of France?"},
    sdk="openai",
)

import openai
openai_client = openai.OpenAI()
response = openai_client.chat.completions.create(**formatted)
print(response.choices[0].message.content)

Environment-Specific Retrieval

import os
from phoenix.client import Client

client = Client()

# Use an environment variable to determine which tag to use
environment = os.environ.get("DEPLOYMENT_ENV", "development")

prompt_version = client.prompts.get(
    prompt_identifier="chat-assistant",
    tag=environment,
)

print(f"Using {environment} prompt version: {prompt_version.id}")

Error Handling

• ValueError -- raised when the prompt or version is not found (HTTP 404). The error message includes the identifier that was not found: "Prompt not found: {prompt_version_id or prompt_identifier}".
• httpx.HTTPStatusError -- raised for other non-success HTTP status codes (e.g., 500 server error, 403 permission denied).
• AssertionError -- raised if neither prompt_version_id nor prompt_identifier is provided, or if the provided values are not strings.

Related Pages

Implements Principle

• Principle:Arize_ai_Phoenix_Prompt_Retrieval