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

# Quickstart

> Install the SDK and track your first AI call.

<Steps>
  <Step title="Install the SDK">
    Install Margovia in the backend app that calls OpenAI, Anthropic, or another model provider.

    <CodeGroup>
      ```bash npm theme={null}
      npm install @margovia/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @margovia/sdk
      ```

      ```bash yarn theme={null}
      yarn add @margovia/sdk
      ```
    </CodeGroup>

    Install the provider SDK you use too:

    <CodeGroup>
      ```bash npm theme={null}
      npm install openai
      ```

      ```bash pnpm theme={null}
      pnpm add openai
      ```

      ```bash yarn theme={null}
      yarn add openai
      ```
    </CodeGroup>
  </Step>

  <Step title="Set your API keys">
    Add the Margovia key to the same backend process that calls your model provider.

    ```env theme={null}
    MARGOVIA_API_KEY=mg_live_xxx
    OPENAI_API_KEY=sk_xxx
    ```

    Installing the SDK alone sends nothing. When `MARGOVIA_API_KEY` is configured, the SDK sends events to Margovia Cloud by default.

    If you self-host Margovia, run a compatible receiver, or test against a local API, set `MARGOVIA_BASE_URL`:

    ```env theme={null}
    MARGOVIA_BASE_URL=http://localhost:4010
    ```
  </Step>

  <Step title="Track an OpenAI call">
    Create a tracked OpenAI client once, then pass Margovia fields beside the real OpenAI request.

    ```ts theme={null}
    import OpenAI from "openai";
    import { Margovia } from "@margovia/sdk";

    const margovia = new Margovia();
    const openai = margovia.openai(new OpenAI());

    await openai.chat.completions.create({
      name: "support_reply",
      outcome: "reply_generated",
      customerId: "workspace_123",
      customerName: "Northstar Agency",
      customerPlan: { name: "pro", monthlyUsd: 99 },
      request: {
        model: "gpt-5-mini",
        messages: [
          { role: "system", content: "Write concise customer support replies." },
          { role: "user", content: "Help me respond to this ticket." }
        ]
      }
    });
    ```

    The tracked client still calls OpenAI. Margovia records the workflow name, customer, token usage, and cost.
  </Step>

  <Step title="Or track an Anthropic call">
    For Anthropic, install the Anthropic SDK instead:

    <CodeGroup>
      ```bash npm theme={null}
      npm install @anthropic-ai/sdk
      ```

      ```bash pnpm theme={null}
      pnpm add @anthropic-ai/sdk
      ```

      ```bash yarn theme={null}
      yarn add @anthropic-ai/sdk
      ```
    </CodeGroup>

    ```ts theme={null}
    import Anthropic from "@anthropic-ai/sdk";
    import { Margovia } from "@margovia/sdk";

    const margovia = new Margovia();
    const anthropic = margovia.anthropic(new Anthropic());

    await anthropic.messages.create({
      name: "score_tweet",
      outcome: "tweet_scored",
      customerId: "workspace_123",
      customerName: "Northstar Agency",
      customerPlan: { name: "pro", monthlyUsd: 99 },
      request: {
        model: "claude-sonnet-4-20250514",
        max_tokens: 800,
        messages: [
          { role: "user", content: "Score this tweet for likely engagement." }
        ]
      }
    });
    ```
  </Step>

  <Step title="Verify tracking">
    Trigger the AI feature you instrumented. For example, submit a support ticket, generate a report, score a tweet, or run the backend route that contains the tracked provider call.

    Then open Margovia and look for the workflow name you sent:

    ```text theme={null}
    support_reply
    ```

    You can also trigger the backend route directly with your usual local tool, such as curl, Postman, a queued job runner, or your app's test console. The important part is that the code path containing the tracked provider call runs once.

    If no API key is configured, the SDK skips Margovia tracking and does not send events.

    If you do not see a run, check:

    * The code ran on your backend, not in the browser
    * `MARGOVIA_API_KEY` is set in the same process that calls OpenAI or Anthropic
    * The API key belongs to the Margovia project you are viewing
    * `MARGOVIA_BASE_URL` is not pointing at a local API by accident
  </Step>
</Steps>

## If you already have a helper

Use `trackAnthropic(...)` or `trackOpenAI(...)` only when you already have your own provider helper function and want to keep that shape.

```ts theme={null}
const response = await margovia.trackAnthropic({
  name: "score_tweet",
  customerId: "workspace_123",
  customerName: "Northstar Agency",
  outcome: "tweet_scored",
  request: params,
  fn: () => anthropic.messages.create(params)
});
```

This replaces manual code that calls `startRun`, `run.trackCost`, and `run.complete`.

Use a raw provider client inside `trackAnthropic(...)` or `trackOpenAI(...)`. Do not pass an already-wrapped client into these helpers or you may double-report cost.

## What `.track(...)` is for

`margovia.track(...)` tracks a workflow boundary. It does not read OpenAI or Anthropic token usage by itself.

Good use:

```ts theme={null}
const openai = margovia.wrapOpenAI(new OpenAI());

await margovia.track({
  name: "generate_weekly_report",
  customerId: "workspace_123",
  outcome: "report_created",
  fn: async () => {
    await openai.chat.completions.create({ model: "gpt-5-mini", messages });
    await openai.chat.completions.create({ model: "gpt-5-mini", messages: followupMessages });
  }
});
```

Bad use:

```ts theme={null}
await margovia.track({
  name: "score_tweet",
  fn: () => anthropic.messages.create(params)
});
```

That bad example creates a run, but if `anthropic` is not wrapped then Margovia receives no token usage and no cost.

## If you use another provider

OpenAI and Anthropic have first-class helpers because the SDK knows how to read their usage fields. For Gemini, Cohere, custom models, search APIs, or internal tools, use manual tracking and send either tokens or `costUsd`.

```ts theme={null}
const run = await margovia.startRun({
  name: "generate_answer",
  customerId: "workspace_123"
});

const response = await gemini.models.generateContent(...);

await run.trackCost({
  provider: "gemini",
  model: "gemini-2.5-pro",
  inputTokens: response.usageMetadata?.promptTokenCount,
  outputTokens: response.usageMetadata?.candidatesTokenCount
});

await run.complete({ outcome: "answer_generated" });
```

See [Integration patterns](/guides/integration-patterns) for unsupported provider examples.

## Attribution checklist

Send attribution from your app's source of truth:

* `customerId`: stable account, workspace, org, tenant, or billing customer ID
* `customerName`: readable display name
* `customerPlan`: current plan name and monthly revenue
* `userId`: optional actor inside that customer account

Prefer namespaced IDs such as `workspace_123`, `org_abc`, or `stripe_cus_123`. Margovia stores the ID exactly as sent so it can join back to your app and billing data.