---
title: "Credit balance, holds, and this month's free grant"
method: GET
path: "/v1/usage"
tags: ["Account"]
---

# Credit balance, holds, and this month's free grant

`GET /v1/usage`

## Request

- Base URL: `https://api.weirapp.io`
- URL: `https://api.weirapp.io/v1/usage`
- Auth: HTTP bearer

Returns the caller's own credit state. Requires authentication but no additional scope, because a key that cannot discover why it is being refused cannot handle being refused.

## Response `200`

The account's credits.

- object
  - `data` object, required
    - `balance` integer, required: Credits the account holds: what is left of this month's free grant plus everything bought. Purchased credits never expire.
    - `reserved` integer, required: Credits held by this account's calls still in flight. Each is charged what it returned and gives the rest back when it finishes.
    - `available` integer, required: balance minus reserved. A billed call is admitted while this covers its minimum charge; below that, calls return 402 until credits are added.
    - `freeGrant` object, nullable, required: This month's free credits, which are spent before anything bought and do not roll over. Null for a workspace that does not receive them: each person's oldest workspace does.
      - `granted` integer, required
      - `remaining` integer, required
      - `resetsAt` string, date-time, required: When this month's free credits expire and next month's arrive.
    - `tier` 'free' | 't1' | 't2' | 't3', required: Raised by lifetime credit purchases, net of refunds: free, then t1 from $5, t2 from $100, t3 from $500. Spending and time never lower it.
    - `spendingPaused` boolean, required: True while a refund or payment dispute on the account is resolved. Billed calls return 402 until then; free calls still work.
  - `meta` object, required
    - `requestId` string, required

## Other responses

- `400`: The request failed validation.
- `401`: The API key is missing, malformed, expired, or revoked.
- `402`: The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes.
- `403`: The API key does not carry the scope this route requires.
- `404`: The account no longer exists.
- `429`: The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again.
- `500`: An unexpected error occurred.

---

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