Data Model - Majordomo

This page documents the columns you’ll see when querying usage directly. Steward writes locally first and batches metadata to Butler; the dashboard reads from Butler’s database.

Steward (gateway) writes request rows immediately to its local DB and uploads bodies to your S3/GCS when configured.
Butler (control plane) ingests usage/metadata in batches from Steward and serves the dashboard/API.
The Web dashboard queries Butler. If you query directly, prefer Butler’s DB for analytics consistency.

llm_requests

One row per proxied request.

Column	Type	Description
`id`	`uuid`	Request id.
`majordomo_api_key_id`	`uuid`	Owning Majordomo API key.
`provider_api_key_hash`	`varchar(64)`	Hash of upstream provider Authorization header.
`provider_api_key_alias`	`varchar(255)`	Optional alias from `X-Majordomo-Provider-Alias`.
`provider`	`varchar(100)`	`openai`, `anthropic`, or `gemini`.
`model`	`varchar(100)`	Model name as reported (or translated).
`request_path`	`text`	Upstream path (e.g., `/v1/chat/completions`).
`request_method`	`text`	HTTP method.
`requested_at`	`timestamptz`	Timestamp when request was received.
`responded_at`	`timestamptz`	Timestamp when response was fully sent.
`response_time_ms`	`int`	Wall-clock response time.
`input_tokens`	`int`	Count parsed from provider response.
`output_tokens`	`int`	Count parsed from provider response.
`cached_tokens`	`int`	Prompt caching read tokens (if applicable).
`cache_creation_tokens`	`int`	Tokens charged to create cache entries.
`input_cost`	`numeric(12,8)`	Calculated cost for input tokens.
`output_cost`	`numeric(12,8)`	Calculated cost for output tokens.
`total_cost`	`numeric(12,8)`	Sum of input/output (and cache) costs.
`status_code`	`int`	Upstream HTTP status.
`error_message`	`text`	Truncated error body when status ≥ 400.
`raw_metadata`	`jsonb`	All custom headers (`X-Majordomo-*`, minus reserved) without indexing.
`indexed_metadata`	`jsonb`	Subset of active keys copied for fast `@>` queries (GIN index).
`request_body`	`text`	Optional local body copy when Postgres body storage is enabled.
`response_body`	`text`	Optional local body copy when Postgres body storage is enabled.
`body_s3_key`	`text`	Object key when uploaded to S3/GCS via personal/org config.
`model_alias_found`	`bool`	True if pricing alias resolved for the model.
`org_id`	`uuid`	Owning org (shadow for filtering/joins).
`created_at`	`timestamptz`	Row creation timestamp.
`synced_to_butler`	`bool`	Steward-only: batched to Butler yet.

Indexes: by (majordomo_api_key_id, requested_at DESC), and a GIN index on indexed_metadata.

llm_requests_metadata_keys

Per-API-key registry of discovered metadata keys and their indexing state.

Column	Type	Description
`majordomo_api_key_id`	`uuid`	API key owner. Part of PK.
`key_name`	`varchar(255)`	Stored name (prefix `X-Majordomo-` is stripped). Part of PK.
`display_name`	`varchar(255)`	UI label.
`key_type`	`varchar(50)`	Semantic hint, default `string`.
`is_required`	`bool`	Reserved for future validation.
`is_active`	`bool`	If true, key is copied into `indexed_metadata`.
`activated_at`	`timestamptz`	When indexing was enabled.
`request_count`	`bigint`	How many requests carried this key.
`last_seen_at`	`timestamptz`	Most recent occurrence.
`hll_state`	`bytea`	HyperLogLog state.
`approx_cardinality`	`int`	Approx unique values for the key.
`hll_updated_at`	`timestamptz`	Last HLL update.
`created_at`	`timestamptz`	Row creation timestamp.

Index: is_active per API key for fast lookups.

Notes

Reserved headers that do not enter raw_metadata: X-Majordomo-Key, X-Majordomo-Provider, X-Majordomo-Provider-Alias.
Bodies in Postgres are off by default; prefer S3/GCS via Cloud Body Storage.

SQL primer

For end‑to‑end examples, see Cost Attribution. A few quick patterns:

-- Last 7 days by day
SELECT date_trunc('day', requested_at) AS day,
       COUNT(*) AS requests,
       SUM(total_cost) AS total_cost
FROM llm_requests
WHERE requested_at >= now() - interval '7 days'
GROUP BY 1
ORDER BY 1;

-- Filter by an indexed metadata key (fast)
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE indexed_metadata @> '{"Feature": "document-review"}';

-- Filter by a non‑indexed key (works, slower)
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE raw_metadata->>'Team' = 'platform';

​llm_requests

​llm_requests_metadata_keys

​Notes

​SQL primer

llm_requests

llm_requests_metadata_keys

Notes

SQL primer