OpenRouter

Overview

OpenRouter is a gateway that gives your application access to models from multiple providers through one API. Confident AI traces and evaluates your OpenRouter calls through confident-trace, Confident AI's OpenTelemetry-native tracing SDK for Python and TypeScript.

The integration captures the following data from supported calls:

• LLM spans — model names, timing, status, and token usage
• Messages — input/output messages and tool-call data returned by the model
• Streaming output — response content as your application consumes it

These examples target the native SDK versions above. TypeScript uses the chatRequest wrapper required by that supported SDK range.

Auto-Instrument

1. Install Dependencies

   Install confident-trace alongside the client used in the examples:

   PythonTypeScript

   pip install confident-trace

2. Set Your API Keys

   Get your project API key from Confident AI and set the credentials for your model client:

   export CONFIDENT_API_KEY="<your-confident-project-key>"
   export OPENROUTER_API_KEY="<your-gateway-key>"

3. Instrument OpenRouter

   Call init() once before making model calls. It instruments the installed native SDK; keep using your client normally.

   PythonTypeScript

   import os
   from confident_trace import init, shutdown
   from openrouter import OpenRouter
   
   init()
   client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])
   
   try:
       response = client.chat.send(
           model="openai/gpt-4o-mini",
           messages=[
               {"role": "user", "content": "Explain OpenTelemetry in one sentence."}
           ],
       )
       print(response.choices[0].message.content)
   finally:
       shutdown()

4. Run OpenRouter

   PythonTypeScript

   python main.py

   Done ✅. Open the Observatory in your Confident AI project to inspect the trace and its model-call spans.

OpenAI-Compatible Clients

If you already use the OpenAI SDK, keep it and point the client at the gateway. Install openai>=1.109,<4 for Python or openai>=7.10.0 <8 for TypeScript alongside confident-trace.

The public endpoint below is detected automatically. For a custom endpoint, also register the exact URL using openrouter_proxy_urls / openrouterProxyUrls.

import os
from openai import OpenAI
from confident_trace import init

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

import OpenAI from "openai";
import { init } from "confident-trace";

const baseURL = "https://openrouter.ai/api/v1";
const runtime = init();
const client = new OpenAI({ baseURL, apiKey: process.env.OPENROUTER_API_KEY! });

These setup snippets replace the quickstart’s client setup; keep its shutdown handling. Use client.chat.completions.create(...) or client.responses.create(...), including streaming. Gateway routing still depends on valid model names and credentials. Matching ignores trailing slashes but includes the scheme, host, port, and full base path.

For manual TypeScript setup, initialize export and use instrumentOpenRouter(client) from confident-trace/openrouter with the native client, or instrumentOpenAI(client) from confident-trace/openai with an OpenAI client. Manual adapters do not require the preload.

What Gets Captured

Each supported application call creates a model-call span. It nests under the active span; without a parent, it starts a new trace.

• Supported APIs — Native chat.send in both languages and Python chat.send_async, including streaming. Native Responses, embeddings, the Agent SDK, and functional SDK helpers are outside this integration.
• Model and usage — the requested model or alias, the returned model when available, response ID, finish reasons, and token counts supplied by the gateway
• Messages and tools — normalized input/output messages and tool-call data; executing a tool is separate work and is not traced by this gateway integration
• Gateway identity — Native SDK spans use the OpenRouter integration label. OpenAI proxy spans retain OpenAI and add confident.gateway.name=openrouter. Both record provider name openrouter.

Messages follow the content policy, including capture opt-out, redaction, and configured size limits. Binary multimodal payloads are omitted.

Streaming

Streaming uses the same setup. Each example includes initialization and shutdown:

import os
from confident_trace import init, shutdown
from openrouter import OpenRouter

init()
client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

try:
    stream = client.chat.send(
        model="openai/gpt-4o-mini",
        messages=[{"role": "user", "content": "Tell me a short story."}],
        stream=True,
    )
    try:
        for chunk in stream:
            print(chunk)
    finally:
        stream.close()
finally:
    shutdown()

import { OpenRouter } from "@openrouter/sdk";
import { init } from "confident-trace";

const runtime = init();
const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY! });

try {
  const stream = await client.chat.send({
    chatRequest: {
      model: "openai/gpt-4o-mini",
      messages: [{ role: "user", content: "Tell me a short story." }],
      stream: true,
    },
  });
  if (!(Symbol.asyncIterator in stream)) {
    throw new Error("Expected a streaming response");
  }
  for await (const chunk of stream) {
    console.log(chunk);
  }
} finally {
  await runtime.shutdown();
}

For Python async code, use await client.chat.send_async(...); consume streams with async for. The TypeScript native SDK is ESM; CommonJS applications can load it with dynamic import().

Set Trace Span Properties

Use a trace context to add properties you know before the call starts. It creates no extra span. Each example initializes tracing and creates its client before making the call.

import os
from confident_trace import init, shutdown, trace_context
from openrouter import OpenRouter

init()
client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

try:
    with trace_context(
        tags=["support"],
        metadata={"gateway": "openrouter"},
        user_id="user-42",
    ):
        response = client.chat.send(
            model="openai/gpt-4o-mini",
            messages=[
                {"role": "user", "content": "Explain OpenTelemetry in one sentence."}
            ],
        )
finally:
    shutdown()

import { OpenRouter } from "@openrouter/sdk";
import { init, traceContext } from "confident-trace";

const runtime = init();
const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY! });

try {
  const response = await traceContext(
    { tags: ["support"], metadata: { gateway: "openrouter" }, userId: "user-42" },
    () =>
      client.chat.send({
        chatRequest: {
          model: "openai/gpt-4o-mini",
          messages: [
            { role: "user", content: "Explain OpenTelemetry in one sentence." },
          ],
        },
      }),
  );
} finally {
  await runtime.shutdown();
}

See trace context for every supported property.

Instrumenting Multi-Turn

You do not need turn() just to trace a single model call. Use it when you want to define a conversational boundary, such as grouping two calls into one turn. Reuse the same thread ID on later turns to group them into one conversation.

Each example includes initialization and shutdown. Use the same environment variables as the quickstart.

import os
from confident_trace import init, shutdown, turn
from openrouter import OpenRouter

init()
client = OpenRouter(api_key=os.environ["OPENROUTER_API_KEY"])

try:
    with turn("support-turn", thread_id="chat-42"):
        context = client.chat.send(
            model="openai/gpt-4o-mini",
            messages=[
                {
                    "role": "user",
                    "content": "List two useful facts about OpenTelemetry.",
                }
            ],
        )
        answer = client.chat.send(
            model="openai/gpt-4o-mini",
            messages=[
                {
                    "role": "user",
                    "content": f"Summarize these facts: {context.choices[0].message.content}",
                }
            ],
        )
finally:
    shutdown()

import { OpenRouter } from "@openrouter/sdk";
import { init, turn } from "confident-trace";

const runtime = init();
const client = new OpenRouter({ apiKey: process.env.OPENROUTER_API_KEY! });

try {
  const answer = await turn({ name: "support-turn", threadId: "chat-42" }, async () => {
    const context = await client.chat.send({
      chatRequest: {
        model: "openai/gpt-4o-mini",
        messages: [
          { role: "user", content: "List two useful facts about OpenTelemetry." },
        ],
      },
    });
    return client.chat.send({
      chatRequest: {
        model: "openai/gpt-4o-mini",
        messages: [
          {
            role: "user",
            content: `Summarize these facts: ${JSON.stringify(context)}`,
          },
        ],
      },
    });
  });
} finally {
  await runtime.shutdown();
}

See threads for conversation grouping and turn properties.

Troubleshooting

• Missing content: check capture settings and the supported API list above. Gateway-side exporters have separate content controls.
• Duplicate records: avoid combining multiple instrumentors for the same client call. Client instrumentation and gateway-side export can also report separate views of one request.

For general setup issues, see troubleshooting.

Disable OpenRouter Instrumentation

Pass init() a list of integration identifiers to opt in to only those integrations. The quickstart uses "openrouter" in Python and "openrouter" in TypeScript. OpenAI proxy clients use "openai", independently of the native gateway integration. An empty list disables all automatic instrumentation:

from confident_trace import init

init(instrumentations=())
# To enable only the quickstart integration: instrumentations=("openrouter",)

import { init } from "confident-trace";

init({ instrumentations: [] });
// To enable only the quickstart integration: instrumentations: ["openrouter"]

Apply the selection to your startup init() call. It controls SDK hooks, not individual gateway hosts, and does not change a gateway’s own export settings. Manually installed TypeScript adapters have their own restoration function.

Next Steps

Last updated on September 11, 2026