TypeScript SDK · Python SDK · HTTP API
Marginal tracks the cost of every LLM call and slices it by the fields you care about — customer, feature, model.
npm install marginal-sdk · pip install marginal-sdk
The dashboard
From “the bill doubled” to a named cause #
Slice spend by what matters in your product, see every dimension charted automatically, and check exactly what your integration sent.
Spot the spike without building a chart
Insights charts spend for every dimension automatically — each model, provider, and registered field gets its own chart. No setup, no query builder.
Know exactly what landed
Every API request is logged with its outcome — accepted counts, rejected events and why, stripped keys, unpriced models. Debug your integration without guessing.
Never a silent $0
Unknown model? The event still lands, flagged as unpriced — visible in the dashboard and the API response, never averaged away. Set a custom price and it applies at ingest.
How it works
One call per LLM request. That's the whole integration. #
- 1
Pick your connection
npm install marginal-sdk
,pip install marginal-sdk
, or no install at all — POST JSON to the HTTP API from any language. The SDKs are zero-dependency, buffered, fire-and-forget: track() never throws and never blocks your request path. - 2
Track each LLM call
Name the provider, paste the response's
model
andusage
as-is — Marginal detects the usage shape and computes the cost server-side against a daily-synced model price catalog. - 3
Slice your spend
Group and filter by customer, feature, model — any field you register. Save the views you keep coming back to.
import { Marginal } from "marginal-sdk";
const marginal = new Marginal({ apiKey: process.env.MARGINAL_API_KEY });
const response = await openai.chat.completions.create({ /* … */ });
marginal.track({
provider: "openai",
model: response.model,
usage: response.usage,
fields: { customer: "acme-corp", feature: "support-bot" },
});
python
import os
from marginal import Marginal
marginal = Marginal(api_key=os.environ["MARGINAL_API_KEY"])
response = client.chat.completions.create(...)
marginal.track(
provider="openai",
model=response.model,
usage=response.usage.model_dump(),
fields={"customer": "acme-corp", "feature": "support-bot"},
)
curl -X POST https://api.marginalhq.com/v1/events \
-H "Authorization: Bearer $MARGINAL_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"events": [
{ "provider": "openai",
"model": "gpt-4o-2024-08-06",
"usage": { "prompt_tokens": 2006, "completion_tokens": 300 },
"fields": { "customer": "acme-corp", "feature": "support-bot" } }
]
}'
The cost lands computed, priced at that day's catalog rates — no token math in your codebase.
Cost observability
Built to answer “why was the bill that high?” #
Slice by any field
Register your vocabulary — customer, feature, anything you slice by — then group or filter spend by it. Unregistered keys are stripped and reported back, so dashboards stay clean.
LLM-aware pricing
Send provider, model, and the response's usage object; cost is computed server-side from a daily-synced price catalog, with per-project overrides. Prices are frozen at ingest.
Saved views
Any Explorer state — range, filters, group-by — saves as a named view. The questions you ask every week are one click away.
SDKs that stay out of the way
TypeScript and Python, zero dependencies. Events buffer locally and flush in batches in the background; network failures retry and then warn — your app never notices. Prefer no SDK? The HTTP API is a single JSON POST.
Let your coding agent do the integration #
Paste marginalhq.com/llms.txt into Claude Code, Cursor, or any coding assistant and it has everything it needs to wire up Marginal — or follow the per-provider recipes yourself.
From zero to a live spend dashboard in five minutes. #
Create a project, register your fields, drop in one track() call. Your next deploy starts answering questions.