Skip to main content

​
Metadata

Emby supports attaching custom metadata to your requests using simple HTTP headers.
This lets you send contextual information such as:
  • Tenant IDs
  • User/session identifiers
  • Application versions
  • Feature flags
  • Country / region metadata
  • AB-test buckets
  • Internal trace IDs
This metadata will appear in your Emby request logs and analytics, giving you fine-grained insights across users, apps, tenants, or features. Future updates will allow segmented cost & latency analytics based on this metadata (e.g., per user, per region, per feature).

​
Using Custom Metadata Headers

To add metadata, include any header beginning with: 
X-Emby-
Example: 
curl -X POST https://api.emby.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMBY_API_KEY" \
  -H "X-Emby-Country: US" \
  -H "X-Emby-User-ID: 9403f741-a524-4b18-b1b2-dbb71cdff2a4" \
  -d '{
    "model": "emby/deepseek-v3",
    "messages": [
      { "role": "user", "content": "Hello, how are you?" }
    ]
  }'
All metadata headers will be visible inside:
  • Emby → Logs
  • Emby → Usage Analytics
  • Per-request inspector

​
Best Practices

Use the `X-Emby-` prefix

All metadata headers should start with
X-Emby-
Example: X-Emby-Tenant-ID.

Consistent naming

Use short, descriptive names separated with hyphens:
X-Emby-App-Version,
X-Emby-Feature.

Avoid sensitive data

Do not include raw PII like email addresses.
Use hashed or anonymized IDs instead.

Keep values small

Keep metadata concise to avoid bloated requests, especially for high-volume applications.

​
Example: Multi-Tenant Platform

Here’s a real-world example for SaaS platforms running multiple tenants: 
curl -X POST https://api.emby.dev/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $EMBY_API_KEY" \
  -H "X-Emby-Tenant-ID: acme-corp" \
  -H "X-Emby-User-ID: user-12345" \
  -H "X-Emby-App-Version: 2.1.4" \
  -H "X-Emby-Feature: chat-assistant" \
  -d '{
    "model": "emby/qwen-3.5-coder",
    "messages": [
      { "role": "user", "content": "Summarize this document..." }
    ]
  }'
This allows Emby to break down analytics by:
  • Tenant
  • User
  • App version
  • Feature or product area
Perfect for understanding usage, cost distribution, performance hotspots, and debugging.

​
What Metadata Enables

Per-Tenant Monitoring

Track latency, errors, and usage across different customers.

Session & Debug Tracing

Pass trace IDs to connect LLM calls to backend logs.

Feature Analytics

See which features or tools drive the most LLM usage.

Cost Breakdown

Attribute spend per tenant, user, region, or version.

​
Need Help Designing Metadata Strategy?

If you want help designing:
  • Tenant-aware billing
  • Usage attribution
  • AB-test instrumentation
  • Observability correlation
  • Multi-region tracking
📞 Book a call: https://cal.com/absolum/30min
💬 WhatsApp us: https://wa.absolum.nl