Metadata

​

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

​

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

​

Where to See Your Metadata

​

Analytics Dashboard

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

​

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

When the same key appears at multiple levels, the precedence order is:

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