Data model: llm_requests and metadata_keys reference

Majordomo stores one row per LLM request in the llm_requests table. You can query this table directly for cost attribution, usage analysis, or debugging. This page is the complete column reference for llm_requests and the companion llm_requests_metadata_keys registry, plus SQL patterns to get you started.

Where data lives

The Majordomo gateway writes request rows immediately to its local database and uploads request/response bodies to your S3 or GCS bucket when cloud body storage is configured.
Majordomo’s cloud control plane ingests usage and metadata in batches and serves the dashboard and API.
If you query the data directly, connect to the same database that the dashboard reads from for consistent results.

llm_requests

One row is written per proxied request.

Column	Type	Description
`id`	`uuid`	Unique request identifier.
`majordomo_api_key_id`	`uuid`	The Majordomo API key that authenticated the request.
`provider_api_key_hash`	`varchar(64)`	Hash of the upstream provider `Authorization` header.
`provider_api_key_alias`	`varchar(255)`	Optional alias set via `X-Majordomo-Provider-Alias`.
`provider`	`varchar(100)`	Provider name: `openai`, `anthropic`, or `gemini`.
`model`	`varchar(100)`	Model name as reported or translated by Majordomo.
`request_path`	`text`	Upstream path (e.g., `/v1/chat/completions`).
`request_method`	`text`	HTTP method of the request.
`requested_at`	`timestamptz`	Timestamp when the request was received by the gateway.
`responded_at`	`timestamptz`	Timestamp when the response was fully sent to the caller.
`response_time_ms`	`int`	Wall-clock response time in milliseconds.
`input_tokens`	`int`	Input token count parsed from the provider response.
`output_tokens`	`int`	Output token count parsed from the provider response.
`cached_tokens`	`int`	Prompt caching read tokens, when 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`	HTTP status code returned by the upstream provider.
`error_message`	`text`	Truncated error body when the status code is 400 or higher.
`raw_metadata`	`jsonb`	All custom `X-Majordomo-*` headers (excluding reserved keys) stored without indexing.
`indexed_metadata`	`jsonb`	Subset of metadata keys copied here for fast `@>` queries (GIN-indexed).
`request_body`	`text`	Local copy of the request body. Only populated when Postgres body storage is enabled.
`response_body`	`text`	Local copy of the response body. Only populated when Postgres body storage is enabled.
`body_s3_key`	`text`	Object key for the body when uploaded to S3 or GCS via cloud body storage.
`model_alias_found`	`bool`	`true` if a pricing alias was resolved for the model name.
`org_id`	`uuid`	Owning organization, used for filtering and joins.
`created_at`	`timestamptz`	Timestamp when the row was created.
`synced_to_butler`	`bool`	Internal sync flag: `true` once the row has been batched to Majordomo Cloud.

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

llm_requests_metadata_keys

A per-API-key registry of every metadata key Majordomo has observed, along with its indexing state and usage statistics.

Column	Type	Description
`majordomo_api_key_id`	`uuid`	API key owner. Part of the primary key.
`key_name`	`varchar(255)`	Stored key name with the `X-Majordomo-` prefix stripped. Part of the primary key.
`display_name`	`varchar(255)`	Human-readable label shown in the dashboard UI.
`key_type`	`varchar(50)`	Semantic type hint. Defaults to `string`.
`is_required`	`bool`	Reserved for future validation.
`is_active`	`bool`	When `true`, this key is copied into `indexed_metadata` on new requests.
`activated_at`	`timestamptz`	Timestamp when indexing was enabled for this key.
`request_count`	`bigint`	Number of requests that have included this key.
`last_seen_at`	`timestamptz`	Timestamp of the most recent request carrying this key.
`hll_state`	`bytea`	HyperLogLog sketch state used for cardinality estimation.
`approx_cardinality`	`int`	Approximate number of unique values observed for this key.
`hll_updated_at`	`timestamptz`	Timestamp of the last HyperLogLog update.
`created_at`	`timestamptz`	Timestamp when this key was first recorded.

Index: is_active per API key for fast dashboard lookups.

Notes

The following reserved headers are never written to raw_metadata: X-Majordomo-Key, X-Majordomo-Provider, and X-Majordomo-Provider-Alias.

Storing request and response bodies in Postgres is disabled by default. For production deployments, use Cloud Body Storage to write bodies to S3 or GCS instead of your database.

SQL primer

For end-to-end examples, see Cost Attribution. A few quick patterns to get started:

-- 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';

Queries against indexed_metadata use the GIN index and are significantly faster than scanning raw_metadata. Promote high-cardinality or frequently-filtered keys to indexed_metadata from the dashboard.

Get Started

How It Works

Integrate

Analyze & Test

Configuration

Enterprise

Reference

Data model: llm_requests and metadata_keys reference

llm_requests

llm_requests_metadata_keys

Notes

SQL primer

Get Started

How It Works

Integrate

Analyze & Test

Configuration

Enterprise

Reference

​llm_requests

​llm_requests_metadata_keys

​Notes

​SQL primer

llm_requests

llm_requests_metadata_keys

Notes

SQL primer