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

# Quickstart

> Install the Carbon SDK, wrap your AI client, and see your first events in the dashboard.

## Prerequisites

* A Carbon account and a space in the [dashboard](https://oncarbon.site/app)
* An application that calls the OpenAI, Anthropic, or Vercel AI SDK

<Steps>
  <Step title="Create an API key">
    In the dashboard, go to **Settings → API Keys** and click **New**.

    <Warning>
      The full key is shown once, right after creation. Copy it before closing
      the modal — afterwards only a key hint is visible.
    </Warning>

    Store the key in your application's environment:

    ```bash .env theme={null}
    CARBON_API_KEY=your-api-key
    ```
  </Step>

  <Step title="Install the SDK">
    <CodeGroup>
      ```bash bun theme={null}
      bun add @carbon-js/sdk
      ```

      ```bash npm theme={null}
      npm install @carbon-js/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @carbon-js/sdk
      ```

      ```bash yarn theme={null}
      yarn add @carbon-js/sdk
      ```
    </CodeGroup>
  </Step>

  <Step title="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.

    <CodeGroup>
      ```typescript OpenAI theme={null}
      import OpenAI from "openai";
      import { Carbon } from "@carbon-js/sdk";
      import { wrapOpenAISdk } from "@carbon-js/sdk/ai";

      // Wrap client with Carbon SDK.
      const carbon = new Carbon();
      const openai = wrapOpenAISdk(new OpenAI(), carbon);

      // Use exactly as before — every call is captured.
      const completion = await openai.chat.completions.create({
        model: "gpt-5.4-nano",
        messages: [{ role: "user", content: "What is the capital of France?" }],
      });
      ```

      ```typescript Anthropic theme={null}
      import Anthropic from "@anthropic-ai/sdk";
      import { Carbon } from "@carbon-js/sdk";
      import { wrapAnthropicSdk } from "@carbon-js/sdk/ai";

      // Wrap client with Carbon SDK.
      const carbon = new Carbon();
      const anthropic = wrapAnthropicSdk(new Anthropic(), carbon);

      // Use exactly as before — every call is captured.
      const message = await anthropic.messages.create({
        model: "claude-haiku-4-5",
        max_tokens: 1024,
        messages: [{ role: "user", content: "What is the capital of France?" }],
      });
      ```

      ```typescript Vercel AI SDK theme={null}
      import * as ai from "ai";
      import { Carbon } from "@carbon-js/sdk";
      import { wrapVercelSdk } from "@carbon-js/sdk/ai";

      // Wrap client with Carbon SDK.
      const carbon = new Carbon();
      const { generateText } = wrapVercelSdk(ai, carbon);

      // Use exactly as before — every call is captured.
      const result = await generateText({
        model: "google/gemini-3-flash",
        prompt: "What is the capital of France?",
      });
      ```
    </CodeGroup>

    `Carbon` reads `CARBON_API_KEY` from the environment by default. You can
    pass `apiKey` explicitly instead — see [Configuration](/documentation/sdk/configuration).

    <Note>
      On serverless platforms like Next.js, Vercel, or AWS Lambda, flush
      buffered events before the function exits — see [Serverless](/documentation/sdk/serverless).
    </Note>
  </Step>

  <Step title="View your events">
    Open [Events](https://oncarbon.site/app/events/all) in the dashboard. Your
    calls appear within seconds, with model, token usage, cost, duration, and
    status. From there, explore [Cost](https://oncarbon.site/app/cost) and the
    per-dimension pages for agents, models, users, threads, and tools.
  </Step>
</Steps>

## Next steps

<Columns cols={3}>
  <Card title="Tag events with context" icon="tag" href="/documentation/sdk/context">
    Add agent, user, thread, and custom dimensions so the dashboard can slice by them.
  </Card>

  <Card title="Correlate with traces" icon="route" href="/documentation/sdk/traces">
    Group the events of one agent run, request, or job under a shared trace ID.
  </Card>

  <Card title="Capture tool calls" icon="wrench" href="/documentation/sdk/tool-calls">
    Wrap your own functions so tool executions show up next to LLM calls.
  </Card>
</Columns>