Respan params & metadata

Tag gateway requests with a customer, a thread, and your own properties.

Respan params are fields you send with a gateway request, next to the standard OpenAI-compatible body. Use them to tag each request with the customer, conversation, and properties you want to find it by in Logs. The full list is in Create chat completion.

Send Respan params

Send them in any of three ways, and combine them if you need to.

response = client.chat.completions.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "customer_identifier": "user_8842",
        "thread_identifier": "thread_7f3a",
        "metadata": {"feature": "support-chat", "environment": "production"},
    },
)

{
  "model": "gpt-5.5",
  "messages": [{"role": "user", "content": "Hello!"}],
  "respan_params": {
    "customer_identifier": "user_8842",
    "metadata": {"feature": "support-chat"}
  }
}

PARAMS=$(echo -n '{"customer_identifier":"user_8842","metadata":{"feature":"support-chat"}}' | base64 | tr -d '\n')

curl https://api.respan.ai/api/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Data-Respan-Params: $PARAMS" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'

If the same field arrives more than one way, respan_params wins over the header, and both win over a top-level field. The exception is variables: top-level variables are merged key by key over the variables from respan_params or the header. The legacy names keywordsai_params and X-Data-Keywordsai-Params still work.

Passthrough endpoints

The passthrough endpoints (Anthropic, OpenRouter, Gemini, and /{provider}/v1/chat/completions) forward your body to the provider in its own format. On these endpoints you can also put respan_params inside the request’s metadata. Respan removes it before the provider sees the body, and its fields override the same fields in a top-level respan_params.

import os
import anthropic

client = anthropic.Anthropic(
    base_url="https://api.respan.ai/api/anthropic/",
    api_key=os.environ["RESPAN_API_KEY"],
)

message = client.messages.create(
    model="claude-sonnet-4-5-20250929",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"respan_params": {"customer_identifier": "user_8842"}},
)

On /api/chat/completions, metadata holds your custom properties, so Respan doesn’t read a respan_params key inside it. Use respan_params or extra_body there.

respan_params must be a JSON object

The easy way to hit this: the OpenAI SDK types metadata as Dict[str, str], so on an OpenAI-compatible passthrough such as OpenRouter it’s tempting to json.dumps the params. That sends a string, which is ignored. Send an object through extra_body instead:

import json
import os
from openai import OpenAI

client = OpenAI(
    base_url="https://api.respan.ai/api/openrouter/v1",
    api_key=os.environ["RESPAN_API_KEY"],
)

# Wrong: metadata.respan_params is a string, so none of it applies
client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
    metadata={"respan_params": json.dumps({"customer_identifier": "user_8842"})},
)

# Right: an object, at the top level of the body
client.chat.completions.create(
    model="openai/gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={"respan_params": {"customer_identifier": "user_8842"}},
)

Common params

In customer_params:

• customer_identifier wins over a top-level customer_identifier.
• name and email are saved only the first time Respan sees the customer.
• rate_limit caps that customer’s requests per minute. Over it, /api/chat/completions returns 429. Other endpoints don’t apply it.
• Budget fields are ignored. Set a customer’s budget in Users or with Update a user.

Params for routing, fallbacks, caching, and prompts are covered on their own pages, starting with Routing.

Find them in Logs

Open Gateway › Logs, click a span, and open the Metadata tab. Properties shows the customer, thread, and custom ID, and Custom properties lists your metadata keys.

Hover Customer ID, Thread ID, or Custom ID and click the filter icon to show only the spans with that value. To group and filter by these fields, see Custom IDs & attributes.

Beta features

Opt in to experimental features with the X-Respan-Beta header. Separate several flags with commas.

curl https://api.respan.ai/api/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -H "X-Respan-Beta: token-breakdown-2026-03-26" \
  -d '{"model": "gpt-5.5", "messages": [{"role": "user", "content": "Hello!"}]}'