Quickstart - Margovia

Install the SDK

Install Margovia in the backend app that calls OpenAI, Anthropic, or another model provider.

npm install @margovia/sdk

pnpm add @margovia/sdk

yarn add @margovia/sdk

Install the provider SDK you use too:

npm install openai

pnpm add openai

yarn add openai

Set your API keys

Add the Margovia key to the same backend process that calls your model provider.

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:

MARGOVIA_BASE_URL=http://localhost:4010

Track an OpenAI call

Create a tracked OpenAI client once, then pass Margovia fields beside the real OpenAI request.

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.

Or track an Anthropic call

For Anthropic, install the Anthropic SDK instead:

npm install @anthropic-ai/sdk

pnpm add @anthropic-ai/sdk

yarn add @anthropic-ai/sdk

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." }
    ]
  }
});

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:

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

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.

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:

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:

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.

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

​If you already have a helper

​What .track(...) is for

​If you use another provider

​Attribution checklist

If you already have a helper

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

If you use another provider

Attribution checklist