Respan params & metadata | Respan Docs
Three ways to send Respan params
You can pass Respan params three ways. They can be combined; later layers override earlier ones (body top-level > respan_params > header).
1. Top-level body fields (simplest)
Most params are accepted directly at the top level of the request body alongside standard OpenAI fields. With the OpenAI SDK, use extra_body.
2. Nested under respan_params
For clarity, or when using the standard API rather than the OpenAI SDK, nest the fields under respan_params.
The legacy key keywordsai_params is still accepted and merged into respan_params.
3. X-Data-Respan-Params header (base64-encoded JSON)
Send a X-Data-Respan-Params header containing base64-encoded JSON. Useful when you cannot modify the request body (for example, when proxying a third-party SDK or CLI through the gateway).
The legacy header X-Data-Keywordsai-Params is still accepted.
Customer & metadata params
| Param | Type | Description |
|---|---|---|
customer_identifier |
string | Tag a request to a specific end-user. Drives the Users page and per-customer analytics. |
metadata |
object | Arbitrary key-value pairs (also called custom properties). All values are stored as strings. Filter, group, and search logs by any key. |
custom_identifier |
string | Extra indexed tag for free-form grouping (shows as “Custom ID” in spans). |
thread_identifier |
string | Group requests that belong to the same conversation thread. |
disable_log |
boolean | When true, only metrics are recorded (no request/response payloads stored). |
request_breakdown |
boolean | Returns a summarization of the response (tokens, cost, latency) inside the response body. |
metadata and “custom properties”
metadata and “custom properties” are the same thing. metadata is the API field name; custom properties is the label used in the platform UI for filtering and grouping. Anything you send as metadata becomes a custom property on the trace and its spans.
You can then filter logs and traces by any of these keys on the Logs page. If you want a high-cardinality key indexed for fast filtering and aggregation, contact us to add it to your org’s indexed property list.
Beta features (X-Respan-Beta header)
Opt in to experimental features via the X-Respan-Beta header. Send comma-separated feature flags.
| Flag | Description |
|---|---|
token-breakdown-2026-03-26 |
Adds best-effort per-part token estimates (system_tokens, tools_tokens, user_message_tokens) to the log’s properties field. |