Metadata - Gatelit

Metadata lets you attach arbitrary key/value tags to any gateway request. The gateway stores them on the log entry, so you can filter, debug, and analyze traffic by business dimensions instead of raw model IDs.

How it works

Send a metadata object in the request body. It never reaches the provider — the gateway strips it before forwarding and stores it on the log entry:

{
  "model": "openai/gpt-4o",
  "messages": [{"role": "user", "content": "Summarize this ticket"}],
  "metadata": {
    "environment": "production",
    "feature": "doc-summariser",
    "session_id": "sess_123",
    "tenant_id": "acme-corp",
    "plan": "enterprise"
  }
}

Rules

Constraint	Value
Value types	`string`, `number`, or `boolean` — nested objects and arrays are rejected with a 400
Key length	64 characters max, non-empty
Value length	128 characters max per string value
Keys	100 max per request

Tracking users

Two separate mechanisms, like the industry-standard gateways:

user (body field) — the standard OpenAI field. Forwarded to the provider unchanged, and used as the logged end-user ID when no other value is present.
endUserId (token claim or x-gatelit-end-user-id header) — Gatelit-only, never sent to the provider. Wins over user when both are present.

For the full channel inventory and why attributes live where they do, see Conventions.

Filtering logs

The dashboard logs page filters on metadata tags with operators. Multiple conditions can be chained — they are combined with AND:

Operator	Example	Matches
`equals`	`environment` = `production`	Exact value match (numbers/booleans match their typed form)
`contains`	`feature` contains `summar`	Value contains the text (substring)
`exists`	`session_id` exists	Key present, any value
`doesn't exist`	`session_id` doesn’t exist	Key absent
`is empty`	`feature` is empty	Key present with empty-string value
`is not empty`	`feature` is not empty	Key present with non-empty value

Example chain: environment equals production and feature contains summar — only requests carrying both tags match. Notes:

contains treats % and _ as wildcards (SQL ILIKE semantics)
Keys with special characters (dots, quotes, spaces) can only be used with equals — the other operators address keys as a single path segment
Conditions that are only partially filled in (e.g. equals without a value) are ignored until completed

Common patterns

Use case	Example keys
Environment segmentation	`environment`, `region`, `deployment`
Feature cost attribution	`feature`, `team`, `version`
Multi-tenant SaaS	`tenant_id`, `tenant_plan`
Session tracking	`session_id`, `turn`
Internal tracing	`request_id`, `service`, `caller`
Prompt experiments	`experiment`, `variant`
Compliance / audit	`user_role`, `data_class`, `regulation`

SDK

The TypeScript SDK exposes metadata and user on ChatOptions:

const response = await client.chat({
  model: "openai/gpt-4o",
  messages: [{ role: "user", content: "Summarize this ticket" }],
  metadata: {
    environment: "production",
    feature: "doc-summariser",
    session_id: "sess_123",
  },
  user: "customer_42",
})

Security

Metadata is visible to dashboard users with access to the org’s logs. Never put secrets, full PII, or credentials in metadata — use opaque identifiers and classification labels.

​How it works

​Rules

​Tracking users

​Filtering logs

​Common patterns

​SDK

​Security