OpenRouter

OpenRouter exposes many models behind an OpenAI-compatible API. Moda captures OpenRouter traffic through the standard openai client pointed at https://openrouter.ai/api/v1 — there is no OpenRouter-specific setup beyond the base URL.

Prerequisites

A Moda API key (created in the dashboard at Settings → Ingestion keys; shown once at creation)
An OpenRouter API key
Python 3.10 or later, or Node.js 18 or later
The openai package (version 4.0.0 or later in Node.js)

Setup

Install the packages

pip install moda-ai openai

npm install moda-ai openai

Point the OpenAI client at OpenRouter

Initialize Moda first, then construct the client with the OpenRouter base URL. Flush before your process exits so buffered data is sent.

import os

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")

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

moda.conversation_id = "session_123"

response = openrouter.chat.completions.create(
    model="anthropic/claude-3-haiku",
    max_tokens=50,
    messages=[{"role": "user", "content": "Say hello in exactly 3 words."}],
)
print(response.choices[0].message.content)

moda.flush()

import { Moda } from 'moda-ai';
import OpenAI from 'openai';

await Moda.init('YOUR_MODA_API_KEY');

const openrouter = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY,
});

Moda.conversationId = 'session_123';

const response = await openrouter.chat.completions.create({
  model: 'anthropic/claude-3-haiku',
  max_tokens: 50,
  messages: [{ role: 'user', content: 'Say hello in exactly 3 words.' }],
});
console.log(response.choices[0].message.content);

await Moda.flush();

In Node.js, Moda.init() is async and the API key argument is required (it is not read from MODA_API_KEY). If Moda.init() is not awaited, calls made before initialization completes are not captured.

Verify in the dashboard

Run the script, then open Conversations in the dashboard. You should see a conversation with ID session_123 containing the user message and the assistant reply, with token counts when OpenRouter returns usage data.

Model naming

OpenRouter model IDs use the provider/model format, for example anthropic/claude-3-haiku or google/gemini-2.0-flash-001. How the model is recorded differs by SDK:

Python: the SDK detects OpenRouter from the base URL and records the model without the provider prefix (anthropic/claude-3-haiku is recorded as claude-3-haiku).
Node.js: the model is recorded as sent and returned, keeping the provider/model format.

You can switch models between calls in the same session; calls stay grouped as long as the conversation ID is the same.

Streaming

Streaming works the same as with OpenAI. The SDK records the complete response after the stream finishes, so consume the entire stream.

import os

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")

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

stream = openrouter.chat.completions.create(
    model="google/gemini-2.0-flash-001",
    max_tokens=50,
    messages=[{"role": "user", "content": "Count to 5"}],
    stream=True,
)
for chunk in stream:
    print(chunk.choices[0].delta.content or "", end="")

moda.flush()

import { Moda } from 'moda-ai';
import OpenAI from 'openai';

await Moda.init('YOUR_MODA_API_KEY');

const openrouter = new OpenAI({
  baseURL: 'https://openrouter.ai/api/v1',
  apiKey: process.env.OPENROUTER_API_KEY,
});

const stream = await openrouter.chat.completions.create({
  model: 'google/gemini-2.0-flash-001',
  max_tokens: 50,
  messages: [{ role: 'user', content: 'Count to 5' }],
  stream: true,
});
for await (const chunk of stream) {
  process.stdout.write(chunk.choices[0]?.delta?.content || '');
}

await Moda.flush();

Tool use

Tool calls made through the openai client go through the same chat completions instrumentation as OpenAI and are captured the same way, when the underlying model supports tools. See the OpenAI tool use example — only the base_url and model name change.

Direct API calls with manual tracing (Node.js)

If you call the OpenRouter HTTP API directly instead of using the openai client, wrap the call with Moda.withLLMCall() (Node.js only) to capture it:

Node.js

import { Moda } from 'moda-ai';

await Moda.init('YOUR_MODA_API_KEY');
Moda.conversationId = 'session_123';

const messages = [{ role: 'user', content: 'Hello!' }];

const result = await Moda.withLLMCall(
  { vendor: 'openrouter', type: 'chat' },
  async ({ span }) => {
    span.reportRequest({ model: 'anthropic/claude-3-haiku', messages });

    const response = await fetch('https://openrouter.ai/api/v1/chat/completions', {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
        'Content-Type': 'application/json',
      },
      body: JSON.stringify({ model: 'anthropic/claude-3-haiku', messages, max_tokens: 50 }),
    });
    if (!response.ok) throw new Error(`API error: ${response.status}`);
    const data = await response.json();

    span.reportResponse({
      model: data.model,
      usage: data.usage,
      completions: data.choices,
    });

    return data;
  }
);
console.log(result.choices[0].message.content);

await Moda.flush();

There is no Python equivalent of withLLMCall; from Python, use the HTTP API or OpenTelemetry for direct API calls.

Support matrix

Capability	Python	Node.js
Chat completions via `openai` client with OpenRouter base URL	Supported	Supported
Streaming	Supported	Supported
Tool use (model-dependent)	Supported	Supported
Token usage	Supported (when OpenRouter returns usage)	Supported (when OpenRouter returns usage)
Model name normalization (`provider/model` prefix stripped)	Applied	Not applied — model keeps the `provider/model` format
Manual tracing of direct HTTP calls (`withLLMCall`)	Not supported — use the HTTP API	Supported

Troubleshooting

No conversations appear in the dashboard. Initialize Moda before constructing the client, and call moda.flush() (Python) or await Moda.flush() (Node.js) before the process exits. In Node.js, confirm Moda.init() is awaited. Token usage is missing. Moda records token counts only when the OpenRouter response includes a usage object. Whether usage is returned depends on OpenRouter and the upstream provider, not on Moda. Model names look different between Python and Node.js apps. Expected — the Python SDK strips the provider/ prefix, the Node.js SDK does not. See Model naming.

Next steps

OpenAI — the underlying client instrumentation, including tool use.
Node.js SDK — init options, scoped context, and withLLMCall reference.
Python SDK — init options and context managers.
HTTP API — send events directly when no SDK path fits.

Send data

SDKs

Providers

Frameworks and agents

OpenTelemetry

API reference

Prerequisites

Setup

Model naming

Streaming

Tool use

Direct API calls with manual tracing (Node.js)

Support matrix

Troubleshooting

Next steps

​Prerequisites

​Setup

​Model naming

​Streaming

​Tool use

​Direct API calls with manual tracing (Node.js)

​Support matrix

​Troubleshooting

​Next steps

Prerequisites

Setup

Model naming

Streaming

Tool use

Direct API calls with manual tracing (Node.js)

Support matrix

Troubleshooting

Next steps