OpenAI

This page shows how to capture OpenAI API traffic with Moda. Once the SDK is initialized, calls made with the official openai client are captured automatically — no changes to the calls themselves.

Prerequisites

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

Setup

Install the packages

pip install moda-ai openai

npm install moda-ai openai

Initialize Moda before creating the client

Initialize the SDK first, then construct the OpenAI client. Flush before your process exits so buffered data is sent.

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")

# Reads OPENAI_API_KEY from the environment
client = OpenAI()

moda.conversation_id = "session_123"

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)
print(response.choices[0].message.content)

moda.flush()

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

await Moda.init('YOUR_MODA_API_KEY');

// Reads OPENAI_API_KEY from the environment
const client = new OpenAI();

Moda.conversationId = 'session_123';

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'Hello!' }],
});
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. In Python, moda.init() is synchronous and also reads the MODA_API_KEY environment variable, so moda.init() with no arguments works when that variable is set.

Verify in the dashboard

Run the script, then open Traces in the dashboard. You should see a trace with ID session_123 containing the user message and the assistant reply, with model gpt-4o and token counts. Analysis signals (emotion, tool failures) typically appear within minutes of ingest.

Trace grouping

Set a trace ID — the conversation_id field — before the first call of a session or run, from your session, thread, job, or run ID, so every call lands in one trace. Use moda.conversation_id (Python) or Moda.conversationId / Moda.withConversationId() (Node.js). See the Python SDK and the Node.js SDK for the full context APIs.

Streaming

Streaming chat completions are captured automatically. The SDK records the complete response after the stream finishes, so consume the entire stream.

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")
client = OpenAI()

stream = client.chat.completions.create(
    model="gpt-4o",
    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 client = new OpenAI();

const stream = await client.chat.completions.create({
  model: 'gpt-4o',
  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

Function calling is captured automatically, including the tool call arguments in the assistant message and any role: "tool" result messages you send in follow-up calls.

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")
client = OpenAI()

response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What's the weather in London?"}],
    tools=[{
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a location",
            "parameters": {
                "type": "object",
                "properties": {"location": {"type": "string"}},
                "required": ["location"],
            },
        },
    }],
)
tool_call = response.choices[0].message.tool_calls[0]
print(tool_call.function.name, tool_call.function.arguments)

moda.flush()

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

await Moda.init('YOUR_MODA_API_KEY');
const client = new OpenAI();

const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: "What's the weather in London?" }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get the current weather for a location',
      parameters: {
        type: 'object',
        properties: { location: { type: 'string' } },
        required: ['location'],
      },
    },
  }],
});
const toolCall = response.choices[0].message.tool_calls?.[0];
console.log(toolCall?.function.name, toolCall?.function.arguments);

await Moda.flush();

Embeddings (Python only)

The Python SDK captures client.embeddings.create() calls. The Node.js SDK does not instrument embeddings — it captures chat completions only.

Python

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")
client = OpenAI()

embedding = client.embeddings.create(
    model="text-embedding-3-small",
    input="The quick brown fox",
)

moda.flush()

To capture embeddings from a Node.js app, send them yourself via OpenTelemetry or the HTTP API.

Support matrix

Capability	Python	Node.js
Chat Completions (`chat.completions.create`)	Supported	Supported
Streaming chat completions	Supported	Supported
Tool use / function calling	Supported	Supported
Token usage (input, output, total)	Supported	Supported
Embeddings	Supported	Not supported — use OpenTelemetry or the HTTP API
Responses API (`responses.create`)	Supported	Not supported
Assistants API	Supported	Not supported
Image generation (`images.generate`)	Supported	Not supported
Legacy completions (`completions.create`)	Supported	Not supported

OpenAI-compatible endpoints reached through the openai client with a custom base URL are also captured — see Azure OpenAI and OpenRouter.

Troubleshooting

No traces appear in the dashboard. Initialize Moda before constructing the OpenAI client, and call moda.flush() (Python) or await Moda.flush() (Node.js) before the process exits. In Node.js, confirm Moda.init() is awaited and the API key starts with moda_sk_. Streaming calls show no assistant message. The response is recorded only after the stream ends. Consume the stream fully; a stream that is abandoned partway is not captured completely. Embeddings calls are missing in Node.js. Expected — the Node.js SDK instruments chat completions only. Use the Python SDK, OpenTelemetry, or the HTTP API. Every request creates a new trace. Set a trace ID before the first call of the session (see Trace grouping above).

Next steps

Python SDK — init options, context managers, and instrument controls.
Node.js SDK — init options, scoped context, and manual tracing.
OpenRouter — capture other models through the same openai client.
Traces — how captured traces appear in the dashboard.

Send data

SDKs

Providers

Frameworks and agents

OpenTelemetry

API reference

Prerequisites

Setup

Trace grouping

Streaming

Tool use

Embeddings (Python only)

Support matrix

Troubleshooting

Next steps

​Prerequisites

​Setup

​Trace grouping

​Streaming

​Tool use

​Embeddings (Python only)

​Support matrix

​Troubleshooting

​Next steps

Prerequisites

Setup

Trace grouping

Streaming

Tool use

Embeddings (Python only)

Support matrix

Troubleshooting

Next steps