--- title: "Me Usage" method: GET path: "/api/v1/me/usage" tags: ["Account"] --- # Me Usage `GET /api/v1/me/usage` ## Request - Base URL: `https://lenz.io` - URL: `https://lenz.io/api/v1/me/usage` - Auth: HTTP bearer Return the calling account's credit balance and what it can still buy. **``credits`` is the balance.** One pool funds every billable capability, at the weights in ``costs`` — today ``verify`` 10, ``assess`` 1, ``ask`` 1. It has two buckets: the monthly allowance for the current ``plan``, which resets at ``resets_at``, and non-expiring ``extra`` credits from grants and top-ups, spent only once the allowance is gone. ``remaining`` is the sum, and is what a call is actually checked against. The current shape is ``credits``, ``costs``, ``cost_options``, ``extract``, ``plan``, ``plan_label`` and ``has_webhook_secret``. Callers on API version ``2026-05-13`` also get the deprecated fields below, which are kept for them: ``credits.bonus``, ``quota_resets_at`` (the same as ``credits.resets_at``) and the ``verify`` / ``ask`` / ``assess`` blocks. ``credits.bonus`` (``2026-05-13`` only) is the deprecated old name of ``credits.extra``, the same number. Read ``extra``. ``plan`` is the stable slug to branch on; ``plan_label`` is the same tier as display copy ("Pro"). Two fields rather than one humanised string, so a reworded label cannot break a client comparing tiers. The Pro plan's ``plan`` is ``pro``; it read ``developer`` before 2026-09-15, while ``plan_label`` already read "Pro". **The per-capability blocks are deprecated** (``2026-05-13`` only). ``verify`` / ``ask`` / ``assess`` are **projections** of that one pool into each capability's own unit — "how many of these could I still make" — not separate allowances. Spending on one moves all of them, and they are floor divisions, so a verify block ticks once per 10 credits spent anywhere. Read ``credits`` and ``costs`` instead; the blocks and the per-block ``credits`` alias stay for ``2026-05-13`` callers. Derive them:: remaining = credits.remaining // costs[capability] total = credits.total // costs[capability] used = total - remaining Two capabilities at the same price emit identical blocks — ``ask`` and ``assess`` are both 1 credit — which is the clearest sign the shape describes an allowance that no longer exists. ``bonus`` in each block is ``credits.extra`` in that capability's unit. The older key ``credits`` is its deprecated alias, kept for the same callers. ``costs`` is one entry per capability at its DEFAULT price. Prices that depend on a request parameter live in ``cost_options``, nested capability → parameter → value — ``{"verify": {"depth": {"standard": 10, "low": 5}}}``. Two maps rather than a flat one with a ``verify_low`` key, so a future tuning parameter nests instead of adding an entry that reads like a fifth capability. Every capability in ``cost_options`` also appears in ``costs`` at its default, so reading only ``costs`` is always correct. ``extract`` is free at the pool (``costs.extract`` is 0) and is bounded by a per-account daily fair-use cap instead, reported separately here and rejected with 429 rather than 402. **Versions.** 200: `2026-10-11` receives `MeUsageOut`, `2026-05-13` receives `MeUsageOutLegacy`; default: `2026-10-11` receives `ErrorOut`, `2026-05-13` receives `ErrorOutLegacy`. ## Headers - `X-Lenz-API-Version` string ## Response `200` OK - MeUsageOut: The calling account's credit balance, and what it can still buy. ``credits`` is the balance and ``costs`` is the price list. Those two, plus ``cost_options``, are the whole contract for a new integration. The current shape is ``credits``, ``costs``, ``cost_options``, ``extract``, ``plan``, ``plan_label`` and ``has_webhook_secret``. Callers on API version ``2026-05-13`` also get the DEPRECATED fields, kept for them: the ``verify`` / ``ask`` / ``assess`` blocks (projections of that same pool into each capability's unit) with their ``credits`` alias, ``credits.bonus`` and ``quota_resets_at``. ``extract`` is free at the pool (``costs.extract`` is 0) and carries a per-account daily fair-use cap instead; it rejects with 429, not 402. The Pro plan's ``plan`` is ``pro`` since 2026-09-15; it was ``developer`` before. ``plan_label`` reads "Pro" either way. - `plan` string - `plan_label` string - `quota_resets_at` string, nullable: Sent only to callers on `2026-05-13`; use `credits.resets_at`. - `credits` MeUsageCreditsOut, required: The account's credit balance — the one pool every capability spends. Two buckets: the monthly allowance for the current plan (resets at ``resets_at``) and non-expiring ``extra`` credits from grants and top-ups, which are spent only once the allowance is gone. ``remaining`` is the sum and is what a call is checked against. ``bonus`` is a DEPRECATED alias of ``extra`` (the balance's name until 2026-09-15); read ``extra``. It stays for existing callers. It was renamed because the balance holds top-ups you paid for as well as grants. - `total` integer - `used` integer - `remaining` integer - `extra` integer - `bonus` integer: Sent only to callers on `2026-05-13`; use `extra`. - `resets_at` string, nullable - `costs` object, required - `cost_options` object - `verify` MeUsageQuotaOut: DEPRECATED. One capability's share of the pool, projected into its unit. Sent only to API version ``2026-05-13`` callers and kept for them, with the per-block ``credits`` alias below. Read ``MeUsageOut.credits`` and ``MeUsageOut.costs`` instead and do the division — it is one line, and it is the same one this block does:: remaining = credits.remaining // costs[capability] total = credits.total // costs[capability] used = total - remaining These are **projections, not allowances**. Every billable capability draws on the single balance in ``MeUsageOut.credits``, at the weight in ``MeUsageOut.costs``; this block answers "how many ``/verify`` calls could I still make if I spent everything on them". Spending on any capability moves every block, and the division floors — a ``verify`` block whose weight is 10 ticks once per 10 credits spent anywhere. They predate the pool, when each really was its own allowance, and that is why the current shape leaves them out: two capabilities at the same price emit byte-identical objects (``ask`` and ``assess`` are both 1 credit today), so the shape suggests a per-capability allowance that no longer exists. ``bonus`` is ``MeUsageOut.credits.extra``, the non-expiring balance, in this capability's unit. ``quota_used`` is derived as ``quota_total - quota_remaining``, so ``used + remaining == total`` always holds. ``credits`` is a DEPRECATED alias of ``bonus``, kept for the same callers; read ``MeUsageOut.credits`` for the pool. It never meant the pool — before the pool existed it meant this capability's one-off top-up balance, which is exactly what ``bonus`` now reports. - `quota_used` integer - `quota_total` integer - `quota_remaining` integer - `bonus` integer - `credits` integer - `remaining` integer - `ask` MeUsageQuotaOut: DEPRECATED. One capability's share of the pool, projected into its unit. Sent only to API version ``2026-05-13`` callers and kept for them, with the per-block ``credits`` alias below. Read ``MeUsageOut.credits`` and ``MeUsageOut.costs`` instead and do the division — it is one line, and it is the same one this block does:: remaining = credits.remaining // costs[capability] total = credits.total // costs[capability] used = total - remaining These are **projections, not allowances**. Every billable capability draws on the single balance in ``MeUsageOut.credits``, at the weight in ``MeUsageOut.costs``; this block answers "how many ``/verify`` calls could I still make if I spent everything on them". Spending on any capability moves every block, and the division floors — a ``verify`` block whose weight is 10 ticks once per 10 credits spent anywhere. They predate the pool, when each really was its own allowance, and that is why the current shape leaves them out: two capabilities at the same price emit byte-identical objects (``ask`` and ``assess`` are both 1 credit today), so the shape suggests a per-capability allowance that no longer exists. ``bonus`` is ``MeUsageOut.credits.extra``, the non-expiring balance, in this capability's unit. ``quota_used`` is derived as ``quota_total - quota_remaining``, so ``used + remaining == total`` always holds. ``credits`` is a DEPRECATED alias of ``bonus``, kept for the same callers; read ``MeUsageOut.credits`` for the pool. It never meant the pool — before the pool existed it meant this capability's one-off top-up balance, which is exactly what ``bonus`` now reports. - `quota_used` integer - `quota_total` integer - `quota_remaining` integer - `bonus` integer - `credits` integer - `remaining` integer - `assess` MeUsageQuotaOut: DEPRECATED. One capability's share of the pool, projected into its unit. Sent only to API version ``2026-05-13`` callers and kept for them, with the per-block ``credits`` alias below. Read ``MeUsageOut.credits`` and ``MeUsageOut.costs`` instead and do the division — it is one line, and it is the same one this block does:: remaining = credits.remaining // costs[capability] total = credits.total // costs[capability] used = total - remaining These are **projections, not allowances**. Every billable capability draws on the single balance in ``MeUsageOut.credits``, at the weight in ``MeUsageOut.costs``; this block answers "how many ``/verify`` calls could I still make if I spent everything on them". Spending on any capability moves every block, and the division floors — a ``verify`` block whose weight is 10 ticks once per 10 credits spent anywhere. They predate the pool, when each really was its own allowance, and that is why the current shape leaves them out: two capabilities at the same price emit byte-identical objects (``ask`` and ``assess`` are both 1 credit today), so the shape suggests a per-capability allowance that no longer exists. ``bonus`` is ``MeUsageOut.credits.extra``, the non-expiring balance, in this capability's unit. ``quota_used`` is derived as ``quota_total - quota_remaining``, so ``used + remaining == total`` always holds. ``credits`` is a DEPRECATED alias of ``bonus``, kept for the same callers; read ``MeUsageOut.credits`` for the pool. It never meant the pool — before the pool existed it meant this capability's one-off top-up balance, which is exactly what ``bonus`` now reports. - `quota_used` integer - `quota_total` integer - `quota_remaining` integer - `bonus` integer - `credits` integer - `remaining` integer - `extract` MeUsageExtractOut, required: Daily ``/extract`` usage (rate-limited per day, not credit-based). ``calls_today`` is the ACCOUNT's counter, shared across all of its keys; ``unlimited`` reports whether the CALLING key bypasses the cap. - `calls_today` integer - `daily_limit` integer - `unlimited` boolean - `has_webhook_secret` boolean ## Other responses - `default`: An error --- [API](https://skmtc.dev/lenz/apis/lenz-ai-fact-checking-api.md) · [All operations](https://skmtc.dev/lenz/apis/lenz-ai-fact-checking-api/llms.txt) · [OpenAPI document](https://skmtc.dev/lenz/apis/lenz-ai-fact-checking-api/revisions/6150947324bf?raw)