Metadata & Attribution

Metadata lets you tag every LLM request with custom attributes like feature name, user ID, and environment. This enables cost attribution, filtering, and analytics.

What Is Metadata?

Metadata is a JSON object attached to each request. It's stored alongside the request log and used for:

  • Cost attribution - See costs broken down by feature or user
  • Filtering - Find requests by metadata fields in the dashboard
  • Analytics - Aggregate metrics by any metadata dimension

Adding Metadata via SDK

Python

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    metadata={
        "feature": "chat_assistant",
        "user_id": "user_123",
        "environment": "production",
        "version": "2.1"
    }
)

JavaScript

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [...],
  metadata: {
    feature: "chat_assistant",
    userId: "user_123",
    environment: "production",
    version: "2.1",
  },
});

Adding Metadata via Headers

When using the proxy directly (without the SDK), pass metadata as a JSON-encoded header:

curl -X POST https://api.proxle.dev/v1/proxy/openai/chat/completions \
  -H "X-Api-Key: pk_live_..." \
  -H "X-Provider-Key: sk-..." \
  -H "X-Metadata: {\"feature\": \"chat\", \"user_id\": \"user_123\"}" \
  -H "Content-Type: application/json" \
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello!"}]}'

Common Metadata Fields

| Field | Description | Used For | |-------|-------------|----------| | feature | Feature or module name | Cost by Feature analytics | | user_id | Your application's user ID | Cost by User analytics | | environment | development, staging, production | Filtering | | version | App version or prompt version | Debugging |

Filtering by Metadata

In the Dashboard > Requests page, use the search box to filter by metadata fields. The search matches against all metadata values.

Cost Attribution

The analytics dashboard automatically groups costs by:

  • Feature - Uses the feature metadata field
  • User - Uses the user_id metadata field

Go to Dashboard > Analytics to view these breakdowns.

Limits

  • Maximum metadata size: 4KB when serialized to JSON
  • All values must be strings or numbers
  • Nested objects are not supported
Request ReplaySupported Providers