Metadata

LLM API lets you attach structured metadata to every request through a set of predefined X-LLMAPI-* HTTP headers. Metadata is indexed, queryable, and powers cost attribution, per-segment analytics, and session correlation.

You can later filter logs by any combination of metadata keys and group usage aggregates by a specific key — for example, to get cost and token usage per team, per environment, or per product feature.

Predefined Headers

Only the following nine headers are recognized. Any other X-LLMAPI-* header is silently dropped.

Header	Purpose	Example Values
`X-LLMAPI-Team`	Team or department attribution	`backend`, `ml-ops`, `data-science`
`X-LLMAPI-Environment`	Deployment environment	`prod`, `staging`, `dev`
`X-LLMAPI-Feature`	Product feature that triggered the call	`chat-assistant`, `code-review`, `summarizer`
`X-LLMAPI-Session-Id`	Multi-turn conversation correlation	A UUID or any client-defined session identifier
`X-LLMAPI-User-Id`	Per-user tracking	Your internal user ID
`X-LLMAPI-Label`	Freeform tag	Any client-defined label
`X-LLMAPI-Trace-Id`	Client-side distributed tracing correlation	Your own trace / correlation ID
`X-LLMAPI-Type`	Business purpose classification	`b2b`, `b2c`, `internal`
`X-LLMAPI-App-Id`	Application or service identifier	Your internal app / service ID

INFO

Header names are case-insensitive — X-LLMAPI-Team, x-llmapi-team, and X-Llmapi-Team are all treated identically. Values are stored verbatim (case-sensitive).

Sending Metadata

Include one or more headers alongside any chat completion, message, or audio request:

curl -X POST https://api.llmapi.ai/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer $LLM_API_KEY" \
  -H "X-LLMAPI-Team: backend" \
  -H "X-LLMAPI-Environment: prod" \
  -H "X-LLMAPI-Feature: chat-assistant" \
  -H "X-LLMAPI-User-Id: user-12345" \
  -d '{
    "model": "gpt-4o",
    "messages": [
      { "role": "user", "content": "Summarize this document..." }
    ]
  }'

Behavior:

Unknown X-LLMAPI-* headers are silently dropped — only the nine headers above are persisted.
Keys are normalized to lowercase when stored, so X-LLMAPI-Team and x-llmapi-team collapse into the same logical key.
Empty values are accepted and stored (useful if you rely on key-existence rather than value matching).
Missing metadata is fine — requests without any X-LLMAPI-* headers simply have no metadata attached.

Filtering Logs by Metadata

The dashboard logs endpoint supports AND-semantics filtering across any combination of metadata keys. Pass one metadata[key]=value param per key:

GET /logs?metadata[x-llmapi-team]=backend&metadata[x-llmapi-environment]=prod

Rules:

Multiple metadata[...] params are combined with AND — results must match every key/value.
Keys must belong to the nine predefined headers. An unknown key returns HTTP 400.
Values are matched exactly (case-sensitive).
Keys in the query are case-insensitive (metadata[X-LLMAPI-Team]=backend works).

Grouping Usage by Metadata

The public usage reports endpoint supports aggregating totals by the distinct values of any metadata key. Use group_by=metadata together with metadata_key to pick the dimension:

# Cost breakdown per team for March 2025
curl "https://api.llmapi.ai/api/v1/organizations/reports/models/usage?start_date=2025-03-01&end_date=2025-03-31&group_by=metadata&metadata_key=x-llmapi-team" \
  -H "Authorization: Bearer your_public_api_key"

Each row in the response has a metadata_value field holding the distinct value of the chosen key. Rows where the chosen key is absent or empty are excluded.

See Usage & Analytics → Models Usage Report for the full endpoint reference.

Example: Per-Team Cost Attribution

A typical rollout pattern for teams sharing a single LLM API organization:

Each team sets X-LLMAPI-Team on every request it makes (via a shared HTTP client or middleware).
Each deployment sets X-LLMAPI-Environment (prod, staging, dev).
The finance report job calls the usage endpoint with group_by=metadata&metadata_key=x-llmapi-team to get cost per team.
Drill-downs filter the logs page with e.g. metadata[x-llmapi-team]=backend&metadata[x-llmapi-environment]=prod to see exactly which requests drove the cost.

Best Practices

Value conventions

Keep values short and consistent — they become aggregation buckets.
Prefer stable identifiers (team slugs, environment names) over human-readable descriptions.
For per-user tracking, consider hashing or anonymizing identifiers before sending.

Data privacy

Metadata values are stored alongside your log rows with the same retention settings as the rest of your request data — see Data Retention for retention levels.
Avoid putting personally identifiable information in X-LLMAPI-User-Id or X-LLMAPI-Label unless your retention setting and internal policies allow it.

Performance

The nine-header allowlist keeps per-request overhead fixed regardless of how many other custom headers your client sends.
Metadata columns are indexed for both key and value lookups, so filtering by metadata in the logs UI is as fast as filtering by model or provider.