> ## Documentation Index
> Fetch the complete documentation index at: https://docs.moda.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Quickstart

> Install the Moda SDK, capture your first OpenAI or Anthropic call, and see the trace in the dashboard.

This guide takes you from an empty project to a trace 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](#anthropic-variant) follows at the end.

## Prerequisites

* A Moda workspace. Moda is invite-only: sign up at [moda.dev/signup](https://moda.dev/signup) to request one, or join a teammate's workspace through their invitation.
* 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.

**1. Install the SDK**

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

```bash pip theme={"dark"}
pip install moda-ai openai
```

```bash npm theme={"dark"}
npm install moda-ai openai
```

> [!NOTE]
>
> The PyPI package is named `moda-ai`, but you import it as `moda`.

**2. 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.

```python Python theme={"dark"}
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()
```

```typescript Node.js theme={"dark"}
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();
```

> [!WARNING]
>
> 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.

> [!NOTE]
>
> 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.

**3. Add trace and user context**

Set a trace ID — the `conversation_id` field (the trace ID) — and a user ID before the first model call of a session or run. Use an identifier your application already has, such as a session, thread, job, or run ID, so every call is attributed to the right trace and user:

```python Python theme={"dark"}
moda.conversation_id = "session_abc123"  # set to None to clear
moda.user_id = "user_42"
```

```typescript Node.js theme={"dark"}
Moda.setConversationId('session_abc123');
Moda.setUserId('user_42');
```

Calls made while these are set are attributed to that trace 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](https://docs.moda.dev/ingestion/python.md) and [Node.js SDK](https://docs.moda.dev/ingestion/node.md) pages for details.

**4. Verify in the dashboard**

Open [https://moda.dev/dashboard](https://moda.dev/dashboard) and go to **Traces**. Your trace appears within minutes of the flush; click the row to open its **Timeline** 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:

```python Python theme={"dark"}
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()
```

```typescript Node.js theme={"dark"}
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 Traces | 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 traces | Set `moda.conversation_id` / `Moda.setConversationId()` before the first call of the session (see step 3). |

## Next steps

* [Moda SDK for Python](https://docs.moda.dev/ingestion/python.md) — init options, context managers, and supported instrumentations.
* [Moda SDK for Node.js](https://docs.moda.dev/ingestion/node.md) — init options, scoped context, manual capture, and OpenTelemetry coexistence.
* [Ingestion overview](https://docs.moda.dev/ingestion/overview.md) — other ways to send data, including OpenTelemetry and the HTTP API.
* [Dashboard overview](https://docs.moda.dev/dashboard/overview.md) — what to look at once data is flowing.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.