Quickstart

This guide takes you from an empty project to a conversation visible in the Moda dashboard. It uses the Moda SDK for Python or Node.js to auto-instrument the OpenAI client library; an Anthropic variant follows at the end.

Prerequisites

A Moda workspace. Accounts are provisioned by the Moda team; teammates join by invitation (Settings → Members & roles).
A Moda API key. Create one in the dashboard at Settings → Ingestion keys — the full key is shown once, at creation.
An OpenAI API key (or an Anthropic API key for the variant below).
Python 3.10 or later, or Node.js 18 or later.

Install the SDK

Install moda-ai alongside the provider client you already use:

pip install moda-ai openai

npm install moda-ai openai

The PyPI package is named moda-ai, but you import it as moda.

Initialize Moda and make a call

Initialize the SDK before you construct the provider client, make the call as usual, and flush before the process exits.

import moda
from openai import OpenAI

moda.init("YOUR_MODA_API_KEY")

client = OpenAI()  # reads OPENAI_API_KEY from the environment
response = client.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "What can you help me with?"}],
)
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 client = new OpenAI(); // reads OPENAI_API_KEY from the environment
const response = await client.chat.completions.create({
  model: 'gpt-4o',
  messages: [{ role: 'user', content: 'What can you help me with?' }],
});
console.log(response.choices[0].message.content);

await Moda.flush();

In Node.js, Moda.init() is asynchronous and must be awaited. If it is not awaited, calls made before initialization completes are not captured. The Node.js SDK also requires the API key as an explicit argument — it does not read a MODA_API_KEY environment variable. Python’s moda.init() is synchronous and falls back to MODA_API_KEY when no key is passed.

The Node.js sample uses top-level await, which requires ES modules ("type": "module" in package.json). In a CommonJS project, wrap the code in an async function.

Add conversation and user context

Set a conversation ID and a user ID before the first model call of a session — use an identifier your application already has, such as a session, thread, or run ID — so every call is attributed to the right conversation and user:

moda.conversation_id = "session_abc123"  # set to None to clear
moda.user_id = "user_42"

Moda.setConversationId('session_abc123');
Moda.setUserId('user_42');

Calls made while these are set are attributed to that conversation and user. Both SDKs also offer scoped forms that are safe in concurrent servers: with moda.set_conversation_id(...) in Python, and withConversationId(...) / withContext(...) (imported from moda-ai) in Node.js. See the Python SDK and Node.js SDK pages for details.

Verify in the dashboard

Open https://moda.dev/dashboard and go to Conversations. Your conversation appears within minutes of the flush; click the row to open its Full Trace view showing the prompt and the model’s response. Emotion, tool-failure, laziness, and hallucination analyses appear on the Signals page within minutes.

Anthropic variant

The SDKs also auto-instrument the Anthropic client libraries. Install with pip install moda-ai anthropic or npm install moda-ai @anthropic-ai/sdk, then:

import moda
from anthropic import Anthropic

moda.init("YOUR_MODA_API_KEY")

client = Anthropic()  # reads ANTHROPIC_API_KEY from the environment
response = client.messages.create(
    model="claude-sonnet-4-20250514",
    max_tokens=1024,
    messages=[{"role": "user", "content": "What can you help me with?"}],
)
print(response.content[0].text)

moda.flush()

import { Moda } from 'moda-ai';
import Anthropic from '@anthropic-ai/sdk';

await Moda.init('YOUR_MODA_API_KEY');

const client = new Anthropic(); // reads ANTHROPIC_API_KEY from the environment
const response = await client.messages.create({
  model: 'claude-sonnet-4-20250514',
  max_tokens: 1024,
  messages: [{ role: 'user', content: 'What can you help me with?' }],
});
console.log(response.content[0].text);

await Moda.flush();

Troubleshooting

Symptom	Fix
Nothing appears in Conversations	Call `moda.init()` / `await Moda.init()` before constructing the provider client, and call `moda.flush()` / `await Moda.flush()` before the process exits.
`401` with `Invalid or expired API key`	The key is wrong or has been revoked. Keys start with `moda_sk_` and are bound to one workspace. Create a new one at Settings → Ingestion keys.
`[Moda] API key is required` (Node.js)	`Moda.init` takes the key as its first argument; the Node.js SDK does not read `MODA_API_KEY` from the environment.
`ModuleNotFoundError: No module named 'moda'`	Run `pip install moda-ai`. The package installs the `moda` import.
`Cannot find module 'moda-ai'`	Run `npm install moda-ai` in the project that makes the LLM calls.
Related calls land in separate conversations	Set `moda.conversation_id` / `Moda.setConversationId()` before the first call of the session (see step 3).

Next steps

Moda SDK for Python — init options, context managers, and supported instrumentations.
Moda SDK for Node.js — init options, scoped context, manual capture, and OpenTelemetry coexistence.
Ingestion overview — other ways to send data, including OpenTelemetry and the HTTP API.
Dashboard overview — what to look at once data is flowing.

Get started

Concepts

Dashboard

Prompt management

Harness

Administration

Prerequisites

Anthropic variant

Troubleshooting

Next steps

​Prerequisites

​Anthropic variant

​Troubleshooting

​Next steps

Prerequisites

Anthropic variant

Troubleshooting

Next steps