Cost Attribution

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",
    }
)

response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=1024,
    messages=[...],
    extra_headers={
        "X-Majordomo-Key": "mdm_sk_your_key_here",
        "X-Majordomo-Feature": "contract-analysis",
        "X-Majordomo-User-Id": "user_456",
    }
)

curl -X POST https://gateway.gomajordomo.com/v1/chat/completions \
  -H "X-Majordomo-Key: mdm_sk_your_key_here" \
  -H "X-Majordomo-Feature: chat" \
  -H "X-Majordomo-Team: product" \
  -H "X-Majordomo-Environment: production" \
  ...

Recommended dimensions

Header	Example values	When to use
`X-Majordomo-Feature`	`chat`, `document-review`, `code-gen`	Per product feature
`X-Majordomo-Team`	`platform`, `data`, `legal`	Per team
`X-Majordomo-Environment`	`production`, `staging`, `dev`	Per environment
`X-Majordomo-User-Id`	`user_123`	Per end user (use an opaque ID, not PII)
`X-Majordomo-User-Tier`	`free`, `pro`, `enterprise`	Per pricing tier
`X-Majordomo-Experiment`	`model-test-v2`	Per 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.

Grouping an agent’s calls

Metadata attributes cost across dimensions (feature, team, user). To instead group the multiple LLM calls of one conversation or agent run into a single run — with a rolled-up cost and a nested waterfall — use Agent Run Tracking. The two compose: tag a run with a trace id and an X-Majordomo-Feature to both drill into one run and roll runs up by feature.

Getting Started

How It Works

Connect Your Code

Track & Analyze

Control

Enterprise

Reference

Adding metadata

Recommended dimensions

Querying spend

By feature

By team (monthly)

By model

Top spenders this week

Indexed metadata

Grouping an agent’s calls

​Adding metadata

​Recommended dimensions

​Querying spend

​By feature

​By team (monthly)

​By model

​Top spenders this week

​Indexed metadata

​Grouping an agent’s calls

Adding metadata

Recommended dimensions

Querying spend

By feature

By team (monthly)

By model

Top spenders this week

Indexed metadata

Grouping an agent’s calls