---
title: "Your account: this billing period's usage + expected next charge"
method: GET
path: "/v1/usage"
---

# Your account: this billing period's usage + expected next charge

`GET /v1/usage`

## Request

- Base URL: `https://api.omniaauto.ca`
- URL: `https://api.omniaauto.ca/v1/usage`
- Auth: HTTP bearer

Returns this calendar month's call count and per-endpoint breakdown (real-time, from the usage meter), `call_allowance` — the hard-stop monthly call allowance and what is left of it, on the plans that have one (on Personal and Pro it is the market-question meter) — an `mcp` object, and the upcoming invoice amount + date from Stripe (metered/subscription plans).

The `mcp` object carries `unique_vehicles_per_month` and `unique_vehicles_disclosed` (the monthly distinct-vehicle ceiling and how much of it you have used), `billed_metric` — `calls` or `vehicles`, i.e. what the plan actually meters — `rows_per_call` (10 on Personal and Pro) and `stats_scope`. On Personal and Pro, `mcp.meters` reports the three independent allowances — `listings`, `price_checks`, `market_questions` — each as `{cap, used, remaining}`. Statistics may scan the whole dataset, so only row-level records returned move `unique_vehicles_disclosed`. `unique_vins_per_month` / `unique_vins_disclosed` are kept as legacy aliases of the two vehicle counters. `free_quota` is likewise a legacy alias of the `call_allowance` block for the retired free keys still in circulation.

On the prepaid **Starter** plan a `credits` object is also returned: `remaining` (call credits left), `expires_next` (the date the soonest-expiring credits are forfeited), `burn_per_day_30d`, `projected_exhaustion`, `runs_out_on` (whichever of those two comes first) and a `lots` array with one entry per purchase or grant, each carrying its own expiry date. Every billable response on a credit key also carries `X-Omnia-Credits-Remaining` and `X-Omnia-Credits-Expire` headers, so a client does not have to call this endpoint to watch its balance. At zero the API answers `402 credits_exhausted` with a top-up link. Not billed and never quota-blocked, and reachable from every plan including MCP-only Agent and Analyst keys.

## Response `200`

usage + call_allowance (legacy alias: free_quota) + mcp (unique_vehicles_per_month, unique_vehicles_disclosed, billed_metric, rows_per_call, aggregates; legacy aliases unique_vins_per_month / unique_vins_disclosed) + next_invoice

## Other responses

- `401`: Missing/invalid key

---

[API](https://skmtc.dev/omniaauto/apis/omniaauto-canadian-vehicle-listings-api.md) · [All operations](https://skmtc.dev/omniaauto/apis/omniaauto-canadian-vehicle-listings-api/llms.txt) · [OpenAPI document](https://skmtc.dev/omniaauto/apis/omniaauto-canadian-vehicle-listings-api/revisions/f46ac0dabe3d?raw)