Skip to main content
Every request through the gateway can carry custom metadata via X-Majordomo-* headers. This metadata is stored with the request log and queryable in the dashboard and directly in Postgres.

​
Adding metadata

Any header prefixed with X-Majordomo- (except -Key and -Provider) is stored as metadata: 
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[...],
    extra_headers={
        "X-Majordomo-Feature": "document-review",
        "X-Majordomo-Team": "legal",
        "X-Majordomo-Environment": "production",
        "X-Majordomo-User-Tier": "enterprise",
    }
)
HeaderExample valuesWhen to use
X-Majordomo-Featurechat, document-review, code-genPer product feature
X-Majordomo-Teamplatform, data, legalPer team
X-Majordomo-Environmentproduction, staging, devPer environment
X-Majordomo-User-Iduser_123Per end user (use an opaque ID, not PII)
X-Majordomo-User-Tierfree, pro, enterprisePer pricing tier
X-Majordomo-Experimentmodel-test-v2Per A/B test or experiment
Start with the dimensions you’ll actually query. You can add more over time — new keys are stored immediately without any schema changes.

​
Querying spend

​
By feature

SELECT
    raw_metadata->>'Feature' AS feature,
    COUNT(*) AS requests,
    SUM(input_tokens) AS input_tokens,
    SUM(output_tokens) AS output_tokens,
    SUM(total_cost) AS total_cost
FROM llm_requests
WHERE raw_metadata->>'Feature' IS NOT NULL
GROUP BY 1
ORDER BY total_cost DESC;

​
By team (monthly)

SELECT
    raw_metadata->>'Team' AS team,
    date_trunc('month', requested_at) AS month,
    SUM(total_cost) AS total_cost
FROM llm_requests
WHERE requested_at > now() - interval '3 months'
GROUP BY 1, 2
ORDER BY 2 DESC, 3 DESC;

​
By model

SELECT
    model,
    COUNT(*) AS requests,
    SUM(total_cost) AS total_cost,
    AVG(response_time_ms) AS avg_latency_ms
FROM llm_requests
GROUP BY model
ORDER BY total_cost DESC;

​
Top spenders this week

SELECT
    raw_metadata->>'User-Id' AS user_id,
    COUNT(*) AS requests,
    SUM(total_cost) AS total_cost
FROM llm_requests
WHERE
    requested_at > now() - interval '7 days'
    AND raw_metadata->>'User-Id' IS NOT NULL
GROUP BY 1
ORDER BY total_cost DESC
LIMIT 20;

​
Indexed metadata

High-cardinality metadata keys (user IDs, experiment names) can be activated for GIN indexing in the dashboard. Activated keys are copied to the indexed_metadata JSONB column, which supports fast @> queries. 
-- Fast query on an indexed key
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE indexed_metadata @> '{"Feature": "document-review"}';
Non-indexed keys are still queryable via raw_metadata — just without the index. Activate keys for dimensions you query frequently.