Prompt management

Prompt management lets you create and update LLM prompts directly in PostHog. When you use prompts through the SDK, they're fetched at runtime with caching and fallback support—so you can iterate on prompts without deploying code.

Why use prompt management?

• Update prompts without code deploys – Change prompts instantly from the PostHog UI
• Non-engineers can iterate – Product and content teams can tweak prompts without touching code
• Track prompt usage – Link prompts to generations to see which prompts drive which outputs
• Versioning – Every change creates an immutable version you can view, compare, or restore
• Labels – Point a label like production at a version and fetch by label, so saving a prompt and releasing it are separate steps
• A/B testing – Compare prompt versions on cost, latency, and eval pass rate using PostHog Experiments

Creating prompts

1. Navigate to Prompt management > Prompts
2. Click New prompt
3. Enter a name for your prompt
4. Write your prompt content, using {{variables}} for dynamic values
5. Click Create prompt

This creates version 1 of your prompt. Each subsequent edit creates a new immutable version.

Markdown preview

When viewing a prompt, markdown rendering is enabled by default, formatting your prompt text with headings, lists, bold, and other markdown elements. Click the markdown icon next to the Prompt label to toggle it off and view plain text. When editing a prompt, the view switches to plain text automatically.

Prompt naming rules

• Names are immutable after creation (cannot be changed)
• Only letters, numbers, hyphens, and underscores allowed (^[a-zA-Z0-9_-]+$)
• Names must be unique within your project

Managing prompts via MCP

You can also manage prompts through the PostHog MCP server using AI agents like Claude Code, Cursor, or any MCP-connected tool.

The MCP server provides six prompt management tools:

This enables teams to manage prompts programmatically from agent workflows without using the web UI.

Template variables

Use double curly braces to define variables in your prompts:

You are a helpful assistant for {{company_name}}.
The user's name is {{user_name}} and their subscription tier is {{tier}}.

Variable names can include letters, numbers, underscores, hyphens, and dots.

Versioning

Every prompt change creates a new immutable version. Previous versions are preserved and accessible.

How versioning works

• The first save creates version 1
• Each subsequent publish increments the version number
• Previous versions are never modified
• By default, the SDK fetches the latest version

Publish a new version

1. Open a prompt and click New version
2. Make your changes
3. Click Publish — the button shows the number the new version will get, for example Publish v4
4. Review the diff of your changes, optionally add a note describing what changed, and confirm

The note appears alongside the version in the Version history sidebar, so you can scan past changes without opening diffs. It can also be set programmatically via the version_description field on the publish API and the MCP prompt-update tool.

If someone else published a new version while you were editing, publishing fails with a warning. Your edits are preserved in the editor — review them against the new latest version and publish again.

Restore a previous version

1. Open a prompt and select a version from the Version history sidebar
2. Click New version — the editor is prefilled with that version's content
3. Edit the prompt content if needed
4. Click Publish and confirm in the review dialog

This publishes the old content as a new version. The original version remains unchanged.

Compare versions

Compare the content of two prompt versions side-by-side to see what changed. This is available for prompts with two or more versions.

To compare versions:

1. Open a prompt and click Compare versions next to the Prompt label
2. The diff view shows the current version against the previous version by default
3. Use the version dropdown to change the comparison target

You can also click the compare icon on any version in the Version history sidebar to compare it with the currently selected version. The comparison target is highlighted with a Comparing tag in the sidebar.

Unchanged regions are automatically collapsed in the diff view. Click Compare versions again to exit the diff view.

Archive a prompt

Click Archive to remove a prompt from active use. This archives all versions of the prompt. Any code fetching the prompt by name stops resolving it. Archiving also removes the prompt's labels.

Labels

A label is a movable pointer to exactly one version of a prompt. Fetching by a label like production returns whatever version the label points to right now.

Labels separate saving a prompt from releasing it. Without labels, code either fetches the latest version (so every save immediately changes what your app uses) or pins a version number (so every release needs a code change). With a label, you edit and publish versions freely, then move the label when a version is ready:

• Release a version by pointing production at it
• Roll back by pointing production at an earlier version
• Your code just fetches by label and never changes

One version can hold several labels (for example production and staging on the same version), but a label always points to exactly one version. Setting a label that already exists on another version moves it there.

Label naming rules

• Lowercase letters, numbers, dots, hyphens, and underscores; must start and end with a letter or number
• Maximum 128 characters
• latest is reserved (it always means the newest version)
• Numbers-only names are not allowed, to avoid confusion with version numbers
• Up to 50 labels per prompt

Managing labels

Set or move a label via the API:

curl -X PUT "https://us.posthog.com/api/environments/:project_id/llm_prompts/name/:prompt_name/labels/production/" \
    -H "Authorization: Bearer $POSTHOG_PERSONAL_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"version": 3}'

Remove a label with a DELETE request to the same URL. You can also manage labels through the MCP tools (prompt-label-set, prompt-label-delete).

How label changes propagate

Moving a label takes effect on the PostHog API within seconds. SDK consumers pick it up when their client-side cache expires, so a moved label is fully live within the SDK cache TTL (5 minutes by default, configurable per fetch).

If your PostHog instance predates prompt labels (self-hosted), the API ignores the label parameter and returns the latest version; the SDKs log a warning when this happens.

Using prompts in code

Prerequisites

• Personal API key (phx_...) – Used as Bearer auth for prompt fetches
• Project Token (phc_...) – Used as token query param so prompt reads are resolved deterministically to the right project
• PostHog SDK – Install the Python or JavaScript SDK with the AI package

When you initialize Prompts with a PostHog client, the SDK uses the client's project token automatically. If you initialize Prompts directly, you must pass both keys. Use your app host (for example, https://us.posthog.com or https://eu.posthog.com) for prompt reads, not an ingestion host like https://us.i.posthog.com.

Python

from posthog import Posthog
from posthog.ai.prompts import Prompts

# Initialize with PostHog client
posthog = Posthog(
    '<your_project_api_key>',
    host='https://us.posthog.com',
    personal_api_key='<your_personal_api_key>'
)
prompts = Prompts(posthog)

# Or initialize directly
prompts = Prompts(
    personal_api_key='<your_personal_api_key>',
    project_api_key='<your_project_api_key>',
    host='https://us.posthog.com'
)

# Fetch the latest version of a prompt
result = prompts.get(
    'support-system-prompt',
    with_metadata=True,  # Returns a PromptResult with prompt, name, version, and source
    cache_ttl_seconds=600,  # Override default 5-minute cache
    fallback='You are a helpful assistant.'  # Used if fetch fails
)

# Fetch the version a label points to (recommended for production apps)
result = prompts.get(
    'support-system-prompt',
    with_metadata=True,
    label='production',
    fallback='You are a helpful assistant.'
)

# Or fetch a specific version
result = prompts.get(
    'support-system-prompt',
    with_metadata=True,
    version=2,
    fallback='You are a helpful assistant.'
)

# Compile with variables
system_prompt = prompts.compile(result.prompt, {
    'company': 'Acme Corp',
    'tier': 'premium',
    'user_name': 'Alice'
})

# Use in your LLM call
# ... your OpenAI/Anthropic call here

JavaScript/TypeScript

import { Prompts } from '@posthog/ai'
import { PostHog } from 'posthog-node'

// Initialize with PostHog client
const posthog = new PostHog('<your_project_api_key>', {
  host: 'https://us.posthog.com',
  personalApiKey: '<your_personal_api_key>'
})

const prompts = new Prompts({ posthog })

// Or initialize directly (without PostHog client)
const prompts = new Prompts({
  personalApiKey: '<your_personal_api_key>',
  projectApiKey: '<your_project_api_key>',
  host: 'https://us.posthog.com'
})

// Fetch the latest version of a prompt
// Returns a PromptResult with prompt, name, version, and source
const result = await prompts.get('support-system-prompt', {
  cacheTtlSeconds: 600,
  fallback: 'You are a helpful assistant.'
})

// Fetch the version a label points to (recommended for production apps)
const result = await prompts.get('support-system-prompt', {
  label: 'production',
  fallback: 'You are a helpful assistant.'
})

// Or fetch a specific version
const result = await prompts.get('support-system-prompt', {
  version: 2,
  fallback: 'You are a helpful assistant.'
})

// Compile with variables
const systemPrompt = prompts.compile(result.prompt, {
  company: 'Acme Corp',
  tier: 'premium',
  userName: 'Alice'
})

// Use in your LLM call
// ... your OpenAI/Anthropic call here

Caching

Prompts are cached on the SDK side to minimize latency and API calls:

• Default TTL: 5 minutes (300 seconds)
• Configurable per-request: Override with cache_ttl_seconds (Python) or cacheTtlSeconds (JS)
• Stale-while-revalidate: If a fetch fails, the cached value is used (even if expired)
• Fallback support: Provide a fallback value that's used when both fetch and cache fail
• Separate entries per fetch type: Latest, pinned-version, and labeled fetches of the same prompt are cached independently. Label moves reach your app when the labeled entry's TTL expires

Linking prompts to traces

To track which prompts and versions are used in which generations, include the $ai_prompt_name and $ai_prompt_version properties when capturing:

response = client.chat.completions.create(
    model="gpt-5",
    messages=[{"role": "system", "content": system_prompt}],
    posthog_properties={
        "$ai_prompt_name": "support-system-prompt",
        "$ai_prompt_version": 2
    }
)

const response = await openai.chat.completions.create({
    model: "gpt-5",
    messages: [{ role: "system", content: systemPrompt }],
    posthogProperties: {
        $ai_prompt_name: "support-system-prompt",
        $ai_prompt_version: 2
    }
})

Once linked, you can:

• Filter generations by prompt name and version
• View related traces from the prompt detail page
• See which specific version was used in each trace
• Analyze which prompt versions perform best

Limits

• Maximum prompt size - 1MB per prompt
• Maximum versions per prompt - 2,000