Credit balance, holds, and this month's free grant
GET /v1/usage
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.
Price: Free.
Rate limit: Counts as 1 request against your per-minute rate limit.
MCP tool: get_usage, on every MCP connection.
Requires an API key, sent as Authorization: Bearer <key>.
Request
curl --request GET \
--url https://api.weirapp.io/v1/usage \
--header "Authorization: Bearer $WEIR_API_KEY"Response
The account's credits.
200
| Field | Type | Required | Notes |
|---|---|---|---|
data |
object | yes | |
data.balance |
integer | yes | Credits the account holds: what is left of this month's free grant plus everything bought. Purchased credits never expire. · min 0 |
data.reserved |
integer | yes | Credits held by this account's calls still in flight. Each is charged what it returned and gives the rest back when it finishes. · min 0 |
data.available |
integer | yes | balance minus reserved. A billed call is admitted while this covers its minimum charge; below that, calls return 402 until credits are added. · min 0 |
data.freeGrant |
object or null | yes | 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. |
data.freeGrant.granted |
integer | yes | min 0 |
data.freeGrant.remaining |
integer | yes | min 0 |
data.freeGrant.resetsAt |
string (date-time) | yes | When this month's free credits expire and next month's arrive. |
data.tier |
string | yes | 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. · free, t1, t2, t3 |
data.spendingPaused |
boolean | yes | True while a refund or payment dispute on the account is resolved. Billed calls return 402 until then; free calls still work. |
meta |
object | yes | |
meta.requestId |
string | yes |
Errors
| Status | Meaning | What to do |
|---|---|---|
400 |
The request failed validation. | The request was malformed. The details object names the field. |
401 |
The API key is missing, malformed, expired, or revoked. | The key is missing, malformed, revoked, or expired. |
402 |
The account is out of credit. Not retryable: this cannot clear until the billing period resets or the plan changes. | Out of credits. Never retry. Only a person can clear it, by adding credits at https://weirapp.io/dashboard/billing. Retrying never will. |
403 |
The API key does not carry the scope this route requires. | The key is valid but lacks the scope this operation needs. |
404 |
The account no longer exists. | No such resource, or it is not public. |
429 |
The per-minute rate limit is exhausted. Retryable: wait for Retry-After and try again. | Rate limited. Retryable: wait for Retry-After, then try again. |
500 |
An unexpected error occurred. | Something failed on our side. Retryable with backoff. |