Documentation

Installation

Install the MarginDash SDK for your language.

npm

npm install margindash

Usage

Track events using the MarginDash TypeScript SDK.

TypeScript

MarginDash SDK Your code

import { MarginDash } from "margindash";
import OpenAI from "openai";

const md = new MarginDash({ apiKey: "YOUR_API_KEY_HERE" }); // Get from Settings page
const openai = new OpenAI();

const response = await openai.chat.completions.create({
  model: "gpt-4o",
  messages: [{ role: "user", content: "Hello!" }],
});

// No prompts or responses ever leave your servers
md.addUsage({
  vendor: "openai",
  model: response.model, // "gpt-4o"
  inputTokens: response.usage!.prompt_tokens, // 1200
  outputTokens: response.usage!.completion_tokens, // 340
});

md.track({
  customerId: user.id, // 8291
  eventType: "summarize",
  revenueAmountInCents: 500,
});

// Events are flushed automatically in the background.
// Before your process exits:
await md.shutdown();

Privacy first: Only the model name and token counts are sent to MarginDash — no request or response content ever leaves your infrastructure. Pass the vendor name and usage via addUsage(), and MarginDash calculates cost from your configured vendor rates. For agent sessions with multiple AI calls, call addUsage() once per call, then track() once to attach them all.

Field Reference

All fields accepted by track() and addUsage().

track() / Event

Field	Type	Required	Description
customerId	string	yes	Your customer identifier. Auto-creates the customer if it doesn’t exist.
eventType	string	no	Category for this event, max 255 characters (default: `ai_request`)
revenueAmountInCents	number	no	Revenue for this event in cents, 0–10,000,000, e.g. 1500 = $15.00 (default: 0)
occurredAt	string	no	ISO 8601 timestamp, e.g. `2025-06-15T14:30:00Z`. Must be within the last 90 days and no more than 1 hour in the future. (default: current time)

addUsage() / Usage

Field	Type	Required	Description
vendor	string	yes	AI vendor name, e.g. `openai`, `anthropic`, `google`. See all vendors and model slugs below.
model	string	yes	AI model slug, e.g. `gpt-4o`, `claude-4-opus`. See all vendors and model slugs below.
inputTokens	number	yes	Input/prompt token count, 0–100,000,000. At least one of inputTokens or outputTokens must be > 0.
outputTokens	number	yes	Output/completion token count, 0–100,000,000

Supported Models

Click a vendor to see valid slugs for the vendor and model fields. You can also fetch this list programmatically via GET /api/v1/models.

alibaba

qwen1.5-110b-chat qwen2-5-coder-32b-instruct qwen2-5-coder-7b-instruct qwen2.5-32b-instruct qwen2-5-72b-instruct qwen-2-5-max qwen-turbo qwen2-72b-instruct qwen3-0.6b-instruct qwen3-0.6b-instruct-reasoning qwen3-14b-instruct qwen3-14b-instruct-reasoning qwen3-1.7b-instruct qwen3-1.7b-instruct-reasoning qwen3-235b-a22b-instruct-2507 qwen3-235b-a22b-instruct-2507-reasoning qwen3-235b-a22b-instruct qwen3-235b-a22b-instruct-reasoning qwen3-30b-a3b-2507 qwen3-30b-a3b-2507-reasoning qwen3-30b-a3b-instruct qwen3-30b-a3b-instruct-reasoning qwen3-32b-instruct qwen3-32b-instruct-reasoning qwen3-4b-2507-instruct qwen3-4b-2507-instruct-reasoning qwen3-4b-instruct qwen3-4b-instruct-reasoning qwen3-5-397b-a17b-non-reasoning qwen3-5-397b-a17b qwen3-8b-instruct qwen3-8b-instruct-reasoning qwen3-coder-30b-a3b-instruct qwen3-coder-480b-a35b-instruct qwen3-coder-next qwen3-max qwen3-max-preview qwen3-max-thinking qwen3-max-thinking-preview qwen3-next-80b-a3b-instruct qwen3-next-80b-a3b-reasoning qwen3-omni-30b-a3b-instruct qwen3-omni-30b-a3b-reasoning qwen3-vl-235b-a22b-instruct qwen3-vl-235b-a22b-reasoning qwen3-vl-30b-a3b-instruct qwen3-vl-30b-a3b-reasoning qwen3-vl-32b-instruct qwen3-vl-32b-reasoning qwen3-vl-4b-instruct qwen3-vl-4b-reasoning qwen3-vl-8b-instruct qwen3-vl-8b-reasoning qwen-chat-14b qwen-chat-72b qwq-32b QwQ-32B-Preview

Installation

Install the MarginDash SDK for your language.

pip

pip install margindash

Usage

Track events using the MarginDash Python SDK.

Python

from openai import OpenAI
from margindash import MarginDash

openai = OpenAI()
md = MarginDash(api_key="YOUR_API_KEY_HERE")  # Get from Settings page

response = openai.chat.completions.create(
    model="gpt-4o",
    messages=[{"role": "user", "content": "Hello!"}],
)

# No prompts or responses ever leave your servers
md.add_usage(
    vendor="openai",
    model=response.model,  # "gpt-4o"
    input_tokens=response.usage.prompt_tokens,  # 1200
    output_tokens=response.usage.completion_tokens,  # 340
)

md.track(
    customer_id=user.id,  # 8291
    event_type="summarize",
    revenue_amount_in_cents=500,
)

# Events are flushed automatically in the background.
# Before your process exits:
md.shutdown()

Privacy first: Only the model name and token counts are sent to MarginDash — no request or response content ever leaves your infrastructure. Pass the vendor name and usage via add_usage(), and MarginDash calculates cost from your configured vendor rates. For agent sessions with multiple AI calls, call add_usage() once per call, then track() once to attach them all.

Field Reference

All fields accepted by track() and add_usage().

track() / Event

Field	Type	Required	Description
customer_id	str	yes	Your customer identifier. Auto-creates the customer if it doesn’t exist.
event_type	str	no	Category for this event, max 255 characters (default: `ai_request`)
revenue_amount_in_cents	int	no	Revenue for this event in cents, 0–10,000,000, e.g. 1500 = $15.00 (default: 0)
occurred_at	str	no	ISO 8601 timestamp, e.g. `2025-06-15T14:30:00Z`. Must be within the last 90 days and no more than 1 hour in the future. (default: current time)

add_usage() / Usage

Field	Type	Required	Description
vendor	str	yes	AI vendor name, e.g. `openai`, `anthropic`, `google`. See all vendors and model slugs below.
model	str	yes	AI model slug, e.g. `gpt-4o`, `claude-4-opus`. See all vendors and model slugs below.
input_tokens	int	yes	Input/prompt token count, 0–100,000,000. At least one of input_tokens or output_tokens must be > 0.
output_tokens	int	yes	Output/completion token count, 0–100,000,000

Supported Models

Click a vendor to see valid slugs for the vendor and model fields. You can also fetch this list programmatically via GET /api/v1/models.

alibaba

REST API

Use the REST API to send events from any language. The TypeScript and Python SDKs wrap this endpoint with automatic batching and retries — use the REST API directly for Go, Rust, Java, or any other language.

POST https://margindash.com/api/v1/events

Authentication

Pass your API key as a Bearer token in the Authorization header. You can find your API key on the Settings page.

SDKs recommended for TypeScript & Python: The official SDKs (npm install margindash / pip install margindash) handle automatic batching, retries, and graceful shutdown. Use this REST API for languages that don’t have an SDK yet.

Example Request

Send a single event with one vendor response:

cURL

curl -X POST https://margindash.com/api/v1/events \
  -H "Authorization: Bearer YOUR_API_KEY_HERE" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "customer_id": "12345",
        "event_type": "summarize",
        "vendor_responses": [
          {
            "vendor_name": "openai",
            "ai_model_name": "gpt-4o",
            "input_tokens": 1200,
            "output_tokens": 340
          }
        ]
      }
    ]
  }'

Response — 200 OK

{
  "results": [
    {
      "id": 42,
      "status": "created"
    }
  ]
}

Field Reference

The request body is a JSON object with an events array. Each event accepts these fields:

Event fields

Field	Type	Required	Description
customer_id	string	yes	Your customer identifier. Auto-creates the customer if it doesn’t exist.
event_type	string	no	Category for this event, max 255 characters (default: `ai_request`)
vendor_responses	array	yes	Array of vendor response objects (see below). At least one required.
revenue_amount_in_cents	number	no	Revenue for this event in cents, 0–10,000,000, e.g. 1500 = $15.00 (default: 0)
occurred_at	string	no	ISO 8601 timestamp, e.g. `2025-06-15T14:30:00Z`. Must be within the last 90 days and no more than 1 hour in the future. (default: current time)

vendor_responses[] fields

Field	Type	Required	Description
vendor_name	string	yes	AI vendor name, e.g. `openai`, `anthropic`, `google`
ai_model_name	string	yes	AI model slug, e.g. `gpt-4o`, `claude-4-opus`
input_tokens	number	yes	Input/prompt token count, 0–100,000,000. At least one of input_tokens or output_tokens must be > 0.
output_tokens	number	yes	Output/completion token count, 0–100,000,000

Supported Models

Click a vendor to see valid slugs for the vendor_name and ai_model_name fields. You can also fetch this list programmatically via GET /api/v1/models.

alibaba

Linking Stripe to Usage Tracking

Store your customer_id in the Stripe customer's metadata, and our invoice sync will automatically match Stripe payments to the correct customer in your dashboard. This ensures that invoice revenue is attributed to the same customer as your events, enabling accurate margin calculations.

Stripe Customer Creation

Store your customer ID in the Stripe customer's metadata:

cURL

curl https://api.stripe.com/v1/customers \
  -u "sk_live_YOUR_KEY:" \
  -d "name=Acme Corp" \
  -d "email=billing@acme.com" \
  -d "metadata[customer_id]=12345"

Developer Note

The ID you pass to Stripe (12345) must exactly match the customer_id you send in your events. If these values don't match, MarginDash cannot link subscription revenue to usage costs, and margin calculations will be inaccurate.

Backfilling Existing Customers

If you already have Stripe customers, you can backfill the metadata[customer_id] with a one-time script. Loop through your customers and update each one with your internal ID.
Existing invoices are automatically re-linked when you update the metadata — no manual re-sync needed.

TypeScript

import Stripe from "stripe";

const stripe = new Stripe("sk_live_YOUR_KEY");

// Your mapping of Stripe customer IDs to internal IDs
const customerMap: Record<string, string> = {
  "cus_ABC123": "12345",
  "cus_DEF456": "67890",
};

for (const [stripeId, internalId] of Object.entries(customerMap)) {
  await stripe.customers.update(stripeId, {
    metadata: { customer_id: internalId },
  });
}

Python

import stripe

stripe.api_key = "sk_live_YOUR_KEY"

# Your mapping of Stripe customer IDs to internal IDs
customer_map = {
    "cus_ABC123": "12345",
    "cus_DEF456": "67890",
}

for stripe_id, internal_id in customer_map.items():
    stripe.Customer.modify(
        stripe_id,
        metadata={"customer_id": internal_id},
    )