Custom Metadata

AgentWatch supports custom metadata tags on proxy requests. Metadata is stored in telemetry logs and can be used for cost attribution, debugging, and filtering.

Usage

Pass metadata as a JSON object in the x-agentwatch-metadata header:

curl https://api.agent-watch.dev/v1/proxy/openai/chat/completions \
  -H "Authorization: Bearer aw_live_token:sk-proj-real-key" \
  -H "Content-Type: application/json" \
  -H "x-agentwatch-metadata: {\"feature\": \"chat_ui\", \"user\": \"123\", \"environment\": \"production\"}" \
  -d '{"model":"gpt-4o","messages":[{"role":"user","content":"Hello"}]}'

Python Example

from openai import OpenAI
import json

client = OpenAI(
    base_url="https://api.agent-watch.dev/v1/proxy/openai",
    api_key="aw_live_token:sk-proj-real-key"
)

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello"}],
    extra_headers={
        "x-agentwatch-metadata": json.dumps({
            "feature": "chat_ui",
            "user": "123",
            "environment": "production"
        })
    }
)

TypeScript Example

import OpenAI from 'openai';

const client = new OpenAI({
  baseURL: "https://api.agent-watch.dev/v1/proxy/openai",
  apiKey: "aw_live_token:sk-proj-real-key"
});

const response = await client.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello" }]
}, {
  headers: {
    "x-agentwatch-metadata": JSON.stringify({
      feature: "chat_ui",
      user: "123",
      environment: "production"
    })
  }
});

Constraints

Constraint	Limit
Max keys	10
Max key length	50 characters
Max value length	100 characters
Value type	String only
Format	JSON object

Invalid or oversized metadata is silently ignored (requests are not blocked).

Use Cases

Cost by Feature

Tag requests by feature to understand which parts of your product are most expensive:

{"feature": "code_review", "team": "backend"}

Cost by User

Track per-user costs for billing or quota enforcement:

{"user_id": "usr_123", "plan": "pro"}

Environment Tagging

Distinguish between development, staging, and production traffic:

{"environment": "staging", "deploy": "v1.2.3"}

Debugging

Tag requests with context for faster debugging:

{"request_id": "req_abc", "trace_id": "trace_xyz"}

Querying Metadata

Metadata is stored as JSONB in Supabase and can be queried using standard PostgreSQL JSON operators:

-- Find all requests tagged with feature=chat_ui
SELECT * FROM llm_request_logs 
WHERE metadata->>'feature' = 'chat_ui';

-- Find all production requests
SELECT * FROM llm_request_logs 
WHERE metadata->>'environment' = 'production';

-- Count requests by feature
SELECT metadata->>'feature', COUNT(*) 
FROM llm_request_logs 
GROUP BY metadata->>'feature';

Dashboard Integration

The AgentWatch dashboard supports filtering by metadata tags. Use the Settings page to configure which metadata keys appear as filter options.