Usage & the Advisor

merido tracks every request and costs it, then turns that history into concrete, actionable savings through the Token-Optimization Advisor — its headline differentiator.

Usage & cost tracking

Each request records its tokens (prompt, completion, cache-read) and an estimated cost, tagged by provider, model, and source. See it:

• CLI: merido gain — requests, total tokens, estimated cost.
• API: GET /api/usage (summary), GET /api/reports (invoice-ready showback/chargeback rollups by cost_center / api_key (shown as the key's name) / user (the key owner) / source / model / day, as JSON, CSV, or Parquet).
• Dashboard: live request feed and usage charts.

Chargeback works with zero client config. Every request is attributed to the gateway key it authenticated with and that key's owner (user) — provision one key per project/person and the Reports page breaks spend down by either, no headers required. Assign a cost_center to a key on the Gateway Keys page to roll several keys into one chargeback bucket.

Source (which tool) is detected automatically from the caller's User-Agent — Claude Code, Cursor, Codex, and common SDKs self-identify, so the "Spend by source" breakdown is populated out of the box. Send an explicit x-merido-source request header to override it with a project/tool label of your choosing.

The Token-Optimization Advisor

The advisor analyzes your recorded usage and recommends specific optimizations, each with an estimated monthly saving and a severity.

• CLI: merido advise lists current recommendations; merido discover does a retrospective scan — total spend, spend anomalies (days that spiked 3×+ over their trailing baseline), and the aggregate monthly savings still on the table.
• API: GET /api/advisor.

Typical things it detects: requests that could run on a cheaper capable model, missed prompt-cache opportunities, output verbosity that Caveman mode would cut, and repetitive prompts a cache would absorb.

Apply engine — with probation & auto-rollback

The advisor doesn't just advise; it can apply a recommendation for you, safely:

• POST /api/advisor/apply applies one action behind a probation window.
• A background guard watches the action's baseline metrics during probation. If applying it makes things worse, it is auto-rolled-back — you don't get stuck with a bad change.
• GET /api/advisor/applied lists applied actions; POST /api/advisor/confirm/{id} promotes one past probation; POST /api/advisor/rollback/{id} reverts it manually.

Permissions and scope. In multi-tenant mode, every advisor action is platform-wide today — the settings store has no per-org dimension yet, so applying, confirming, or rolling one back requires a platform-admin session on top of ManagePolicy. A tenant Owner/Admin without the platform-admin claim gets a clear 403, and a management token never qualifies. Each action keeps exactly ONE shared platform record: retrying is idempotent, any platform admin from any organization sees and can manage it, and rolling it back then reapplying starts new history. Reading history only needs ViewUsage, but a non-platform-admin caller never sees the shared record. Per-org actions land once each action's setting key and its data-plane reader are scoped by organization end to end; advisor.apply and advisor.rollback audit entries record scope: "global" in the meantime.

Which recommendations have an Apply button. A one-click apply is offered only for the output-invariant levers — the ones that don't change the answer your model returns:

• Prompt caching — places cache breakpoints on the specific model the advisor flagged (so it actually takes effect for that route).
• Compression — flips the global tool-result compression toggle. Compression is on by default, so the button appears only when it's actually off; otherwise the card is plain guidance.

Recommendations that change the output you receive — switching to a cheaper model, Caveman terse mode, or a cascade route — stay advice-only (guidance, no button) until a quality-aware guard can prove a one-click change is safe. This is enforced for direct typed API calls too: switch_cheaper_model, enable_caveman, and cascade_route return 422 with code: "unsupported_action" rather than creating an inert applied-action row.

Proof during probation. GET /api/advisor/applied reports each action's baseline snapshot alongside a freshly-measured one — scoped to traffic recorded after the action was applied, using each request's real recorded outcome and cost rather than assuming every request succeeded — so the dashboard shows a genuine before→after read while it's on probation. For prompt caching, the cache-read fraction climbing is the headline signal; both the baseline and the probation reading narrow it to the flagged model, so the proof reflects that route rather than the whole org.

No confirm without evidence. An action only leaves probation on its own once it has BOTH survived long enough AND actually seen enough real traffic since it was applied — one with no post-apply requests (or only requests from before it was applied) stays on probation past the usual window instead of being waved through on the clock alone.

This "recommend → apply with rollback" loop is what makes the advisor safe to act on rather than just read.

Related

• Token saving and Caching — the levers the advisor pulls.
• Virtual models & fallback — where cheaper-target recommendations land.
• Monitoring — the Live feed, Logs, Reliability, and Reports it sits alongside.