Respan params & metadata

Respan params are platform-specific fields you send alongside the standard OpenAI-compatible payload. They power user analytics, custom-property filtering, log controls, prompt management, and more. This page covers the observability and metadata params. For routing controls (models, credential_override, X-Respan-Route-Provider) see Providers & models. For reliability params (fallback_models, load_balance_group, retry_params) see Reliability.

See the full schema in Create chat completion and Create response.

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.

1
from openai import OpenAI
2
3
client = OpenAI(
4
    base_url="https://api.respan.ai/api/",
5
    api_key="YOUR_RESPAN_API_KEY",
6
)
7
8
response = client.chat.completions.create(
9
    model="gpt-4o-mini",
10
    messages=[{"role": "user", "content": "Hello"}],
11
    extra_body={
12
        "customer_identifier": "user_123",
13
        "metadata": {"feature": "chatbot", "environment": "production"},
14
    },
15
)

2. Nested under respan_params

For clarity, or when using the standard API rather than the OpenAI SDK, nest the fields under respan_params.

1
{
2
  "model": "gpt-4o",
3
  "messages": [{"role": "user", "content": "Hello"}],
4
  "respan_params": {
5
    "customer_identifier": "user_123",
6
    "metadata": {"feature": "chatbot"},
7
    "disable_log": false
8
  }
9
}

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).

$
PARAMS=$(echo -n '{"customer_identifier":"user_123","metadata":{"feature":"chatbot"}}' | base64)
$
$
curl -X POST https://api.respan.ai/api/chat/completions \
>
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
>
  -H "X-Data-Respan-Params: $PARAMS" \
>
  -d '{"model": "gpt-4o", "messages": [{"role": "user", "content": "Hello"}]}'

The legacy header X-Data-Keywordsai-Params is still accepted.

Customer & metadata params

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.

1
response = client.chat.completions.create(
2
    model="gpt-4o-mini",
3
    messages=[{"role": "user", "content": "Hello"}],
4
    extra_body={
5
        "metadata": {
6
            "feature": "chatbot",
7
            "environment": "production",
8
            "customer_tier": "pro",
9
        },
10
    },
11
)

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.

$
curl -X POST https://api.respan.ai/api/chat/completions \
>
  -H "Authorization: Bearer YOUR_RESPAN_API_KEY" \
>
  -H "X-Respan-Beta: token-breakdown-2026-03-26" \
>
  -d '{"model": "gpt-4o", "messages": [...]}'