Implementation:Arize ai Phoenix PromptVersionTags Create

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

Overview

Concrete tools for creating and listing prompt version tags provided by the arize-phoenix-client Python package through the PromptVersionTags class.

Description

The PromptVersionTags class exposes two methods for managing tags on prompt versions:

• create() -- attaches a named tag (e.g., "production", "staging") to a specific prompt version. If the tag already exists on another version of the same prompt, it is moved to the specified version, making tag reassignment an atomic operation.
• list() -- retrieves all tags currently associated with a specific prompt version.

Tags serve as mutable pointers into the immutable version history. Applications reference prompts by tag name (via Prompts.get(prompt_identifier="name", tag="production")) rather than by version ID, enabling deployment changes without code modifications.

The class is accessed through the tags property on the Prompts resource: client.prompts.tags.create(...) and client.prompts.tags.list(...).

Usage

Use these methods when:

• Promoting a validated prompt version to a deployment environment (e.g., tagging it as "production").
• Setting up environment-based deployment pipelines with tags like "development", "staging", and "production".
• Rolling back a deployment by moving a tag to a previously validated version.
• Auditing which tags are currently assigned to a specific version.

Code Reference

Source Location

• Repository: Phoenix
• File: packages/phoenix-client/src/phoenix/client/resources/prompts/__init__.py (lines 163-289)
  • PromptVersionTags class: lines 163-289
  • create(): lines 204-249
  • list(): lines 251-289

Signature: create()

def create(
    self,
    *,
    prompt_version_id: str,
    name: str,
    description: Optional[str] = None,
) -> None

Signature: list()

def list(
    self,
    *,
    prompt_version_id: str,
) -> list[v1.PromptVersionTag]

Import

from phoenix.client import Client

client = Client()
# Access via: client.prompts.tags.create(...)
# Access via: client.prompts.tags.list(...)

I/O Contract

create() Inputs

Name	Type	Required	Description
prompt_version_id	str	Yes	The unique identifier of the prompt version to tag. This is the server-assigned ID returned when a version is created.
name	str	Yes	The name of the tag. Should be a descriptive identifier for the deployment environment or purpose (e.g., "production", "staging", "canary").
description	Optional[str]	No	An optional description providing context about why this version was tagged (e.g., "Passed evaluation with 95% accuracy").

create() Outputs

Name	Type	Description
return value	None	The method returns nothing on success. Raises httpx.HTTPStatusError on failure.

list() Inputs

Name	Type	Required	Description
prompt_version_id	str	Yes	The unique identifier of the prompt version whose tags should be retrieved.

list() Outputs

Name	Type	Description
return value	list[PromptVersionTag]	A list of tag objects associated with the prompt version. Each tag contains at least a name field and optionally a description field.

Usage Examples

Tag a Version for Production

from phoenix.client import Client
from phoenix.client.types.prompts import PromptVersion

client = Client()

# Create a new prompt version
version = PromptVersion(
    [
        {"role": "system", "content": "You are a helpful assistant."},
        {"role": "user", "content": "Answer the question: {{question}}"},
    ],
    model_name="gpt-4o",
    model_provider="OPENAI",
)

created = client.prompts.create(name="qa-assistant", version=version)

# Tag the version for production deployment
client.prompts.tags.create(
    prompt_version_id=created.id,
    name="production",
    description="Validated with 92% accuracy on QA benchmark",
)

Set Up Environment Tags

from phoenix.client import Client

client = Client()

# Assume we have a version ID from a previous create() call
version_id = "abc-123"

# Tag for multiple environments
environments = [
    {"name": "development", "description": "Active development version"},
    {"name": "staging", "description": "Ready for integration testing"},
]

for env in environments:
    client.prompts.tags.create(
        prompt_version_id=version_id,
        **env,
    )

Promote a Version Through Environments

from phoenix.client import Client

client = Client()

# The staging version has been validated; promote it to production
# by moving the "production" tag to the staging version ID
staging_version = client.prompts.get(
    prompt_identifier="qa-assistant",
    tag="staging",
)

client.prompts.tags.create(
    prompt_version_id=staging_version.id,
    name="production",
    description="Promoted from staging after validation",
)

List Tags for a Version

from phoenix.client import Client

client = Client()

version_id = "abc-123"

tags = client.prompts.tags.list(prompt_version_id=version_id)

for tag in tags:
    print(f"Tag: {tag['name']}")
    if "description" in tag:
        print(f"  Description: {tag['description']}")

Rollback Production to a Previous Version

from phoenix.client import Client

client = Client()

# Suppose the current production version is causing issues.
# Roll back by tagging the previous known-good version as production.
previous_good_version_id = "abc-002"

client.prompts.tags.create(
    prompt_version_id=previous_good_version_id,
    name="production",
    description="Rollback: reverted due to regression in v3",
)

API Endpoints

create()

Issues an HTTP POST request to:

v1/prompt_versions/{prompt_version_id}/tags

Request body:

{
  "name": "production",
  "description": "optional description"
}

list()

Issues an HTTP GET request to:

v1/prompt_versions/{prompt_version_id}/tags

Response body:

{
  "data": [
    {
      "name": "production",
      "description": "Validated with 92% accuracy"
    },
    {
      "name": "staging",
      "description": "Integration testing"
    }
  ]
}

Error Handling

• httpx.HTTPStatusError -- raised by both create() and list() if the server returns a non-success HTTP status code. Common causes include:
  • 404 -- the specified prompt_version_id does not exist.
  • 400 -- invalid tag name format.
  • 403 -- insufficient permissions to create or list tags.

Related Pages

Implements Principle

• Principle:Arize_ai_Phoenix_Prompt_Version_Tagging