Marginal

Marginal is an AI cost observability tool that lets developers track, attribute, and analyze LLM spending across their applications. It integrates via a TypeScript SDK, Python SDK, or direct HTTP API, and computes costs server-side against a daily-synced model price catalog — so no token math lives in your codebase. The tool is built for teams who need to answer "why was the bill that high?" with a named cause rather than a raw total.

What It Is

Marginal is a cost-tracking and observability layer for LLM-powered applications. Developers send one event per LLM call — provider, model, and the raw usage object from the API response — and Marginal handles pricing, attribution, and visualization. The dashboard slices spend by any field the developer registers, such as customer ID or product feature, and charts every dimension automatically without requiring a query builder.

How the Integration Works

The integration is designed to be minimal and non-blocking:

• TypeScript SDK (npm install marginal-sdk) — zero dependencies, fire-and-forget; track() never throws and never blocks the request path. Events buffer locally and flush in batches in the background.
• Python SDK (pip install marginal-sdk) — same design; events flush automatically at exit or on explicit shutdown().
• HTTP API — a single JSON POST to https://api.marginalhq.com/v1/events; no install required, works from any language.

The track() call accepts provider, model, usage (pasted as-is from the LLM response), and a fields map of registered keys. Cost is computed server-side at ingest using prices frozen at that day's catalog rates.

Field-Based Attribution

Marginal's core concept is the registered field. Developers declare a vocabulary of keys — up to 20 — on the project's Fields page. Common conventions are customer (who the cost is attributable to) and feature (which part of the product made the call). Events carrying unregistered keys have those keys stripped and reported back, keeping dashboards clean. Any registered field can be used as a Group By or filter in the Explorer view, and saved views let teams bookmark the slices they check regularly.

Dashboard and Observability Features

• Insights — every model, provider, and registered field gets its own spend chart automatically; no setup or query builder needed.
• Ingest log — every API request is logged with its outcome: accepted counts, rejected events with reasons, stripped keys, and unpriced models. Each entry is tagged success, warn, or error.
• Unpriced model handling — if a model isn't in the catalog, the event still lands and is flagged as unpriced rather than silently averaged away. A custom price can be set and applies at ingest going forward.
• Explorer — group and filter spend by any registered field or built-in dimension (model, provider); save views for recurring questions.
• Overview — all-time total, daily cards, and a spend chart.

Coding Agent Support

Marginal publishes an llms.txt file at marginalhq.com/llms.txt that coding assistants such as Claude Code or Cursor can consume to wire up the integration automatically. The docs also include per-provider integration recipes covering OpenAI, Anthropic, Vercel AI SDK, Gemini, Bedrock, and streaming responses.