This feature is available on all Portkey plans.

​
What is Metadata?

Metadata in Portkey allows you to attach custom contextual information to your AI requests. Think of it as tagging your requests with important business context that helps you:
  • Track usage across different users, environments, or features
  • Filter logs to isolate specific request types
  • Analyze patterns in how your AI is being used
  • Audit activities for compliance and security
# Example metadata
{
    "_user": "user-123",      # Who made this request?
    "environment": "prod",    # Where was it made from?
    "feature": "chat-assist", # What feature was using AI?
    "request_id": "42aff12"   # Your internal tracking ID
}

​
Quick Implementation

from portkey_ai import Portkey

portkey = Portkey(
    api_key="PORTKEY_API_KEY",
    virtual_key="OPENAI_VIRTUAL_KEY"
)

# Add metadata to track context
response = portkey.with_options(
    metadata={
        "_user": "user-123",
        "environment": "production",
        "feature": "summarization",
        "request_id": "1729"
    }
).chat.completions.create(
    messages=[{"role": "user", "content": "Summarize this article"}],
    model="gpt-4"
)

​
Common Use Cases

User Analytics

Track which users are using AI features by adding the _user identifier in metadata

Cost Attribution

Attribute AI costs to teams, features or products by adding identifiers in metadata

Environment Tracking

Differentiate between dev/staging/prod usage with the environment metadata key

Feature Usage

See which product features are using AI most heavily with feature identifiers

​
Metadata Keys and Values

  • You can send any number of metadata keys with each request
  • All values must be strings with a maximum length of 128 characters
  • Keys can be any string, but some have special meaning (like _user)

​
Special Metadata Keys

KeyPurposeNotes
_userUser trackingPowers user-level analytics in the Portkey dashboard
About the _user key: If you pass a user field in your OpenAI request body, we’ll automatically copy it to the _user metadata key. If both exist, the explicit _user metadata value takes precedence.

​
Where to See Your Metadata

​
Analytics Dashboard

Analytics dashboard has a dedicated Tab to view aggregate stats on all your metadat keys:
Analytics with metadata filters

​
Request Logs

You can also apply any metadata filters to the logs or analytics and filter data by any metadata key you’ve used:

​
Enterprise Features

For enterprise users, Portkey offers advanced metadata governance and lets you define metadata at multiple levels:
  1. Request level - Applied to a single request
  2. API key level - Applied to all requests using that key
  3. Workspace level - Applied to all requests in a workspace

Enforcing Required Metadata

Define mandatory metadata fields that must be included with all requests
 When the same key appears at multiple levels, the precedence order is:
  1. Workspace metadata (highest priority)
  2. API key metadata
  3. Request metadata (lowest priority)
Please note that before 1.10.20, the precedence order was:
  1. Request metadata (highest priority)
  2. API key metadata
  3. Workspace metadata (lowest priority)

​
Best Practices

  • Use consistent keys across your organization
  • Create naming conventions for metadata keys
  • Consider adding these common fields:
    • _user: Who initiated this request
    • environment: Which environment (dev/staging/prod)
    • feature or component: Which part of your product
    • version: API or app version
    • session_id: To group related requests
    • request_id: Your internal tracking ID
  • For proper tracking, always include the _user field when the request is on behalf of an end-user