Skip to main content
Every request can include custom X-Majordomo-* headers. The gateway stores these as metadata on each request. The dashboard auto-discovers keys and lets you:
  • Set a human‑friendly display name
  • Mark keys Active to index them for fast filtering and breakdowns
Active keys are copied into an indexed JSONB column for @> queries and high‑cardinality analytics.

​
Where to manage keys

  • In the dashboard: Usage → Metadata Keys
You’ll see all keys discovered across your API keys, with request count, approximate unique values, and last seen.

​
Making a key discoverable

Send any request with the header set, for example: 
X-Majordomo-Feature: document-review
X-Majordomo-Team: legal
X-Majordomo-Environment: production
X-Majordomo-User-Id: user_123
The X-Majordomo- prefix is stripped in storage, so these become Feature, Team, Environment, and User-Id.

​
Activating a key (indexing)

  1. Open Usage → Metadata Keys
  2. Locate the key and click “Active” to toggle it on
  3. Optionally click the Display Name to set a friendlier label (e.g., User ID)
After activation, reports and filters that rely on indexed_metadata become fast and scalable for that key.

​
Using active keys in filters

  • Usage pages and Replay/Evals creation dialogs include metadata filters. Active keys appear in the pickers; values are matched using the indexed column.

​
Best‑practice dimensions

  • Feature — product feature or surface
  • Team — owning or chargeback team
  • Environment — prod/staging/dev
  • User-Id — opaque end‑user identifier (do not place PII here)
  • User-Tier — free/pro/enterprise
  • Experiment — A/B test or model switch campaign
Start with what you actually query. You can add keys at any time — no schema change is required.

​
Query examples

For indexed keys (fast): 
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE indexed_metadata @> '{"Feature": "document-review"}';
For non‑indexed keys (still works, slower): 
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE raw_metadata->>'Team' = 'platform';
See also: Cost Attribution.

​
Notes

  • Reserved headers are not treated as metadata: X-Majordomo-Key, X-Majordomo-Provider, X-Majordomo-Provider-Alias.
  • Avoid PII in metadata values. Prefer opaque IDs.