---
title: "Current period usage for the calling key"
method: GET
path: "/v1/usage"
tags: ["Keys"]
---

# Current period usage for the calling key

`GET /v1/usage`

## Request

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

Free, and does not consume a document.

## Response `200`

Usage for the current UTC month.

- object
  - `tier` string, required
  - `period` string, required
  - `used` integer, required
  - `limit` integer, required
  - `remaining` integer, required
  - `resets_at` string, date-time, required
  - `past_due` boolean, required: True when the last subscription payment failed and the provider is still retrying. The paid allowance is UNCHANGED while this is true; only if every retry fails does the key drop to the free tier. This is the only in-band billing warning the API gives — poll it if you want to detect trouble programmatically.
  - `billing_warning` string: Human-readable explanation, present only when past_due is true.
  - `portal_endpoint` string: The ROUTE that mints a billing-portal link — not a link. Always `/v1/billing/portal`. Call it with the customer's own key and it returns a one-time URL where they change plan, update the card, download invoices and cancel. It is an endpoint rather than a URL because Paddle has no static portal page: each link is a session bound to one customer and it expires, so there is nothing durable to publish here, and minting one on every `/v1/usage` poll would spend a live API call on a link nobody opens. Present on `/v1/usage` only for keys that actually have a subscription — a free key has nothing to manage, and pointing one at a route that will answer 409 is worse than saying nothing. Absent, never null.
  - `tier_expires` string, date-time: Present only on a key whose tier is TIME-LIMITED — today, a key minted by an Invoice Fix Report claim (POST /v1/fix/claim), which carries 30 days of starter. Published both before and after the date passes: once past, `tier` above already reads `free`, and this field is the whole explanation of why. The key itself never expires and is never deleted; only the monthly allowance changes.

## Other responses

- `401`: Missing or unknown API key.
- `410`: The key presented was retired by an earlier rotation. Its replacement is the live credential; this one is permanently gone, so retrying with it cannot work. Every authenticated endpoint answers this, not just /v1/keys/rotate.
- `500`: Unhandled fault while reading the meter. Never expected; the body carries no detail on purpose (a fault message can quote the offending value). Retry, and email hello@attestwire.com if it persists.

---

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