---
title: "Read this month's usage and remaining quota"
method: GET
path: "/v1/usage"
tags: ["usage"]
---

# Read this month's usage and remaining quota

`GET /v1/usage`

## Request

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

Returns the monthly usage summary for the calling tenant: the plan quota, the requests counted so far and the requests still available. Defaults to the current month (UTC); pass `month=YYYY-MM` for another. Figures come from the billing aggregates and can lag real time by up to about an hour, so use this for reporting, not for deciding whether the next call will succeed. For an hour-by-hour view use `getUsageHourly`.

## Query parameters

- `month` string: Calendar month (UTC) as YYYY-MM. Defaults to the current month.

## Response `200`

Monthly usage summary.

- UsageResponse
  - `tenantId` string, required
  - `month` string, required: The calendar month (UTC) this response covers.
  - `monthlyQuota` integer, required: Requests included in the plan for a month.
  - `totalRequests` integer, required: Requests counted against the monthly quota so far, combined across every API key, client IP and access surface.
  - `availableRequests` integer, required: max(monthlyQuota - totalRequests, 0). On plans that bill overage, reaching zero means the next request is billed as overage rather than blocked.

## Other responses

- `400`: The request failed validation (malformed JSON, bad field, unparseable target, or a body over 8 KB).
- `401`: The API key is missing, malformed, unknown or revoked.
- `402`: The tenant is suspended for non-payment.
- `403`: The request is not allowed: the key lacks the required scope or the account has been blocked (`forbidden`), or the plan does not include the feature (`plan_feature_unavailable`).
- `429`: The per-minute rate limit (`rate_limited`) or the monthly quota (`quota_exceeded`) was exceeded. Blocked requests are not billed. Back off for `Retry-After` seconds.
- `500`: Unexpected failure. Never contains stack traces, internal hostnames or upstream error bodies.
- `503`: Authentication is temporarily unavailable for a key that has not been seen recently. Retry shortly.

---

[API](https://skmtc.dev/skanqrcode/apis/skanqrcode-api.md) · [All operations](https://skmtc.dev/skanqrcode/apis/skanqrcode-api/llms.txt) · [OpenAPI document](https://skmtc.dev/skanqrcode/apis/skanqrcode-api/revisions/f307ade24b00?raw)