Skip to main content

​
Prerequisites

  • A Carbon account and a space in the dashboard
  • An application that calls the OpenAI, Anthropic, or Vercel AI SDK
1

Create an API key

In the dashboard, go to Settings → API Keys and click New.
The full key is shown once, right after creation. Copy it before closing the modal — afterwards only a key hint is visible.
Store the key in your application’s environment:
.env
CARBON_API_KEY=your-api-key
2

Install the SDK

bun add @carbon-js/sdk
3

Wrap your AI client

Create a Carbon instance and wrap the SDK you already use. The wrapper preserves your existing call sites; events are captured automatically.
import OpenAI from "openai";
import { Carbon } from "@carbon-js/sdk";
import { wrapOpenAISdk } from "@carbon-js/sdk/ai";

const carbon = new Carbon();
const openai = wrapOpenAISdk(new OpenAI(), carbon);

const completion = await openai.chat.completions.create({
  model: "gpt-5.4-nano",
  messages: [{ role: "user", content: "What is the capital of France?" }],
});
Carbon reads CARBON_API_KEY from the environment by default. You can pass apiKey explicitly instead — see Configuration.
4

Flush before exit

The SDK buffers events and flushes them in the background. Long-running servers need no extra code. In serverless and other short-lived environments — scripts, CLIs, batch jobs — flush before exiting so buffered events are not lost:
await carbon.flushPendingEvents();
5

View your events

Open Events in the dashboard. Your calls appear within seconds, with model, token usage, cost, duration, and status. From there, explore Cost and the per-dimension pages for agents, models, users, threads, and tools.

​
Next steps

Add traces and context

Correlate related calls with a trace ID and tag events with agent, user, and thread identifiers.

Capture tool calls

Wrap your own functions so tool executions show up next to LLM calls.