Logs

Every call is logged and every request is a trace, with nothing to install.

The gateway writes a log for each provider call it makes and groups the logs of one request into a trace. You don’t add an SDK or a tracer: sending the request through the gateway is enough. Each response names its log, so you can jump from your code to the call in the platform.

curl -i https://gateway.respan.ai/v1/chat/completions \
  -H "Authorization: Bearer $RESPAN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-5.5",
    "messages": [{"role": "user", "content": "Hello!"}],
    "customer_identifier": "user_8842",
    "thread_identifier": "thread_7f3a",
    "span_name": "support-reply",
    "metadata": {"feature": "support-chat"}
  }'

import os
from openai import OpenAI

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

raw = client.chat.completions.with_raw_response.create(
    model="gpt-5.5",
    messages=[{"role": "user", "content": "Hello!"}],
    extra_body={
        "customer_identifier": "user_8842",
        "thread_identifier": "thread_7f3a",
        "span_name": "support-reply",
        "metadata": {"feature": "support-chat"},
    },
)
print(raw.headers.get("x-respan-log-id"))
response = raw.parse()

import OpenAI from "openai";

const client = new OpenAI({
  baseURL: "https://gateway.respan.ai/v1",
  apiKey: process.env.RESPAN_API_KEY,
});

const body = {
  model: "gpt-5.5",
  messages: [{ role: "user", content: "Hello!" }],
  customer_identifier: "user_8842",
  thread_identifier: "thread_7f3a",
  span_name: "support-reply",
  metadata: { feature: "support-chat" },
};

const { data, response } = await client.chat.completions
  .create(body as OpenAI.ChatCompletionCreateParamsNonStreaming)
  .withResponse();
console.log(response.headers.get("x-respan-log-id"));

What you can do

Response headers

Both are set before the gateway calls a provider, so a streamed response carries them in its headers, and so does a refused request that wrote a log.

One log per call

A plain chat request makes one provider call and writes one log. A request that moves on to a later attempt, such as a fallback in a route, or runs your project’s tools, makes several calls, and each is its own log. Logs are typed by what they are: chat, embedding, image, speech, transcription, video, or tool.

Each log carries the model you asked for and the model that answered, the provider, the status code, whether it streamed, latency and time to first token, token usage, cost, the billing method, and the Respan params you sent. The input and output are kept too, unless you send disable_log: true, which keeps the metadata and drops the content.

A call that never reached a provider is recorded as well. A request refused by a limit policy or a customer budget gets a failed log with the reason, at $0. A request refused by a rate limit or the payment check writes no log. Calls on your own provider key are logged the same way as calls on credits.

One trace per request

• Trace ID: your trace_unique_id if you send one, otherwise the request’s X-Respan-Gateway-Request-Id.
• Root log: the first log, the one X-Respan-Log-Id names. It’s named by your span_name, else trace_name, else after the call.
• Children: every other log of the request.

To join gateway calls to a trace your app already has, send the same trace_unique_id on each request. To group the turns of a conversation, send the same thread_identifier. See Threads and traces.

The first call’s log is published as soon as it ends. The other logs of the request are published when the request ends.

Tag calls

Send these next to the normal request body. With the OpenAI SDK, pass them in extra_body (Python) or as extra fields (TypeScript). They’re never sent to the provider.

You can also send them in a respan_params object or the X-Data-Respan-Params header (base64 JSON). See Respan params for the full list.

Find a call in Logs

Open Gateway › Logs and paste the X-Respan-Log-Id value into the search, or filter by Customer ID, Model, Status code, or Deployment. Group by Traces to see a request with its tool calls.

Click a log to open the side panel. The Metadata tab shows the customer, thread, and your custom properties, and the Config tab shows the Billing method.

For search syntax and filters, see Logs and Inspect spans and traces. To read logs from code, use List spans or Get a trace.

Logs are kept for your project’s retention period. See Data retention and ZDR.

Next steps

• Usage accounting: tokens and cost on each call.
• Reports: totals over time.
• Webhooks: get each call or trace pushed to your URL.