---
title: "Your consumption and remaining allowance for this period"
method: GET
path: "/v1/usage"
---

# Your consumption and remaining allowance for this period

`GET /v1/usage`

## Request

- Base URL: `https://agentmandate-api.com`
- URL: `https://agentmandate-api.com/v1/usage`
- Auth: HTTP bearer

Reports what YOUR ACCOUNT has consumed in the current quota period, the ceiling being enforced against it, and when that ceiling resets. The allowance belongs to the account, not to a key: every key you hold for this API draws on the same budget, so "used" is the total across all of them and a new key does not arrive with a fresh one. Free, and it consumes no quota, so it still answers once you are getting 429 quota_exceeded — which is the point: compare "used" against "ceiling" and read "period.resetsAt" to tell a period you have simply exhausted from a plan that is no longer active, which shows as a "status" of canceled and a ceiling of 0. "used" counts billing units (see "unit"), not HTTP requests: a single request can consume several. All money is in integer minor units (cents), never a decimal. The period reported here is the quota period — the calendar month in UTC, resetting at 00:00 UTC on the 1st. Your invoice window is anchored to the date you subscribed and is a different window; the amounts here are what this period’s usage has accrued so far, not a bill.

## Response `200`

Success

- object
  - `product` string: The API this key is bound to. A key works only on one.
  - `tier` string, nullable: The plan tier you are billed on, e.g. "developer". Null on a free sandbox key with no paid plan.
  - `status` 'sandbox' | 'active' | 'past_due' | 'canceled': State of your plan. "sandbox" means no paid plan; "canceled" explains a ceiling of 0.
  - `unit` string: The billing unit this API meters. "used", "included", "ceiling" and "remaining" are all counted in these, not in requests.
  - `period` object: The quota period: the calendar month in UTC.
    - `start` string, date-time: 00:00 UTC on the 1st of the current month.
    - `resetsAt` string, date-time: When "used" returns to 0 — 00:00 UTC on the 1st of next month.
  - `included` integer: Units your flat monthly fee already covers, before overage pricing applies. 0 without a paid plan.
  - `used` integer: Units your account has consumed so far this period, summed across every key you hold for this API.
  - `ceiling` integer, nullable: The hard limit enforced against your ACCOUNT: requests on any of its keys are refused once the total passes it. Null means unlimited.
  - `remaining` integer, nullable: ceiling minus used, never below 0. Null when the ceiling is unlimited.
  - `overageSoFarMinor` integer: What this period’s usage beyond "included" has accrued, in minor units, before your spend cap is applied. 0 without a paid plan.
  - `spendCapMinor` integer: The most the overage part of one period can ever cost you, in minor units. Your flat base fee is separate and is never capped away.
  - `requestId` string: Quote this when reporting a problem.

## Other responses

- `400`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `401`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `429`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.
- `500`: Deterministic error. Branch on `code`; quote `requestId` when reporting a problem.

---

[API](https://skmtc.dev/agentmandate-api/apis/agent-mandate.md) · [All operations](https://skmtc.dev/agentmandate-api/apis/agent-mandate/llms.txt) · [OpenAPI document](https://skmtc.dev/agentmandate-api/apis/agent-mandate/revisions/463fe122c4d8?raw)