# Marginal

> Marginal tracks the cost of every LLM call and slices it by fields you define — customer, feature, model — with server-side pricing and a live spend dashboard.

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.

## Features
- LLM cost tracking per API call
- Server-side cost computation from daily-synced model price catalog
- Custom field registration for spend attribution (customer, feature, etc.)
- Explorer with group-by and filter on any registered field
- Saved views for recurring spend queries
- Automatic spend charts per model, provider, and registered field
- Ingest log with per-request outcomes (accepted, rejected, stripped keys, unpriced models)
- Unpriced model flagging with custom price override
- TypeScript SDK (zero dependencies, fire-and-forget)
- Python SDK (zero dependencies, auto-flush)
- HTTP API (single JSON POST, no install required)
- Per-project API keys
- Timezone-aware daily charts
- llms.txt for coding agent integration
- Per-provider integration recipes (OpenAI, Anthropic, Vercel AI SDK, Gemini, Bedrock, streaming)

## Integrations
OpenAI, Anthropic, Google Gemini, AWS Bedrock, Vercel AI SDK, Claude Code, Cursor

## Platforms
WEB, API, DEVELOPER_SDK, CLI

## Pricing
Freemium — Free tier available with paid upgrades

## Links
- Website: https://marginalhq.com
- Documentation: https://marginalhq.com/docs
- EveryDev.ai: https://www.everydev.ai/tools/marginal