Usage and balance

GET /v1/usage reports what your key may call and how much of its budget is used. Use it to show a balance in a client, warn before a key runs out, or explain a 422 budget error. It works for every key, including keys restricted to the model routes; the gateway looks your key up itself, so no management-route access is needed.

Try it with your own key in the live playgrounds →

curl -sS "https://llms.party/v1/usage" \
  -H "Authorization: Bearer $LLMS_PARTY_KEY"

const response = await fetch('https://llms.party/v1/usage', {
  headers: { authorization: `Bearer ${process.env.LLMS_PARTY_KEY}` },
});
const usage = await response.json();
console.log(usage.budget.remaining_usd);

import os
import requests
 
response = requests.get(
    "https://llms.party/v1/usage",
    headers={"Authorization": f"Bearer {os.environ['LLMS_PARTY_KEY']}"},
    timeout=30,
)
print(response.json()["budget"]["remaining_usd"])

The response describes the key that made the request:

{
  "key": {
    "alias": "laptop",
    "status": "active",
    "models": ["deepseek-flash", "deepseek-v4-pro", "minimax-h3"],
    "expires_at": null
  },
  "budget": {
    "limit_usd": 25,
    "spent_usd": 1.23,
    "remaining_usd": 23.77,
    "duration": "30d",
    "resets_at": "2026-11-01T00:00:00Z"
  },
  "usage": {
    "total_spent_usd": 4.56,
    "last_active": "2026-10-19T06:36:51Z"
  },
  "limits": {
    "rpm": null,
    "tpm": null
  }
}

Fields

Field	Meaning
`key.alias`	The key's label, or `null`.
`key.status`	`active`, `expired`, `revoked` or `deleted`.
`key.models`	Model groups this key may call; the same list as `GET /v1/models`.
`key.expires_at`	When the key stops working, or `null` for no expiry.
`budget.limit_usd`	Budget for the current window, or `null` when the key has no budget cap.
`budget.spent_usd`	Spend in the current budget window.
`budget.remaining_usd`	`limit_usd - spent_usd`, or `null` when there is no cap.
`budget.duration`	Budget window, for example `30d`, or `null`.
`budget.resets_at`	When the current window ends and `spent_usd` resets to zero.
`usage.total_spent_usd`	Lifetime spend recorded for this key.
`usage.last_active`	Last request made with the key, or `null`.
`limits.rpm` / `limits.tpm`	Per-key request and token-per-minute limits, or `null`.

Budget windows

When budget.duration is set, budget.spent_usd covers only the current window and budget.resets_at is when that window resets — it is not the key's lifetime. The lifetime figure is usage.total_spent_usd.

The gateway checks the budget before each request and does not reserve it for work in progress. Video jobs are charged when they report cost, so concurrent creates can overspend before the next call is rejected; see Errors & limits. Give a key enough budget for a whole video lifecycle, not just task creation.

Errors

Status	Meaning
`401`	Missing, malformed, revoked or expired key.
`502`	Usage information is temporarily unavailable; retry later.

The endpoint reads the key from the Authorization header only. It never accepts a key as a query parameter and only ever returns the calling key's information.