> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gomajordomo.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Metadata Keys

> Discover, name, and activate metadata keys to power fast filtering and breakdowns in usage, Replay, and Evals.

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:

```http theme={null}
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):

```sql theme={null}
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE indexed_metadata @> '{"Feature": "document-review"}';
```

For non‑indexed keys (still works, slower):

```sql theme={null}
SELECT COUNT(*), SUM(total_cost)
FROM llm_requests
WHERE raw_metadata->>'Team' = 'platform';
```

See also: [Cost Attribution](/guides/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.