ShvIA
TIMELINE
SIGN IN

Docs · Native API

Usage and cost

How much you have used, against which limits, and what it cost. All of these endpoints are GET, need your API key, and only describe your own account.

What counts#

Usage is read from the record the gateway keeps of every model call, on every surface: the /v1 endpoints, the native chat endpoints and the apps. Only successful calls count. A call that was refused, or that failed, adds nothing. Embeddings and audio are not counted.

A token is counted once: tokens in plus tokens out make total_tokens. Models on the operator's own servers count as well as cloud models.

GET/api/v1/usage#

Your token quota windows. It is the right call for a usage meter or a pre-flight check before a batch of work.

json
{
  "today": { "used": 19, "limit": 1000000, "remaining": 999981, "reset_at": "2026-10-11T00:00:00+00:00" },
  "week":  { "used": 19, "limit": 7000000, "remaining": 6999981, "reset_at": "2026-10-14T14:00:00+00:00" },
  "month": { "used": 19, "limit": 15000000, "remaining": 14999981, "reset_at": "2026-11-01T00:00:00+00:00" }
}
  • limit is set by the operator for your account group. A limit of -1 means no limit, and remaining is then null.
  • The windows are in UTC: the day resets at midnight, the month on the first, and the week on Wednesday at 14:00. At the end of a month, when the next month is shorter, month.reset_at can show a date a month too late: the month itself always resets on the first.
  • remaining does not subtract the reservation that a call in flight makes, so under parallel load the gateway can refuse a call a little earlier than remaining suggests.

When a limit is reached, calls are refused with 403. See rate limits and quotas.

GET/api/v1/usage/resumo#

A summary for a period. The periodo query is 30d (the default), 90d or ano, and any other value means 30 days.

The response is in Portuguese keys, for historical reasons. The important parts:

KeyContent
periododias, inicio and fim of the window
atualrequests, tokens, usd, the part of the tokens that had no price (tokens_sem_preco), and breakdowns por_origem, por_modelo (the top 5 by tokens) and por_semana
anteriorusd and tokens of the window just before, with the same length
deltathe change from anterior to atual, in percent, or null without a baseline
usd_brlthe exchange rate used for display

Two cautions. usd mixes the cost reported by the providers with an estimate from a price table, and it leaves out tokens that have no price, such as the operator's own models: "no price" is not "free", so read tokens_sem_preco beside it. And por_origem[].origem is a label that changes with your language: use its codigo.

GET/api/v1/usage/providers#

Spend per cloud provider, for today, this week, this month and in total (the total covers the retention period of the records, 180 days by default).

json
{
  "currency": "USD",
  "show_brl": true,
  "usd_brl": 5.4,
  "windows": {
    "month": {
      "providers": [
        { "server_key": "anthropic", "label": "Anthropic (nuvem)", "tokens_in": 120000, "tokens_out": 18000, "requests": 64, "est_cost_usd": 0.63, "has_real_cost": false, "unpriced_tokens": 0 }
      ],
      "est_cost_usd_total": 0.63,
      "unpriced_tokens_total": 0
    }
  },
  "live_balances": {}
}

est_cost_usd is the cost the provider reported when there is one, and otherwise tokens times the price table; has_real_cost says which. When unpriced_tokens is above 0 the cost is incomplete. The operator's own servers are not listed.

live_balances asks each provider for your remaining balance with your key. It only works for providers that offer a balance call, and it can make this endpoint slow on a cold cache.

GET/api/v1/conversations/{id}/usage#

The tokens and cost of one stored conversation:

json
{
  "status": "success",
  "data": {
    "conversation_id": 3,
    "prompt_tokens": 24,
    "completion_tokens": 7,
    "total_tokens": 19,
    "assistant_replies": 1,
    "cost_real_usd": 0,
    "cost_estimated_usd": 0,
    "cost_total_usd": 0,
    "models": ["claude-sonnet-4-6"]
  }
}

cost_real_usd adds up what the providers reported. cost_estimated_usd adds up estimates from the price table. The numbers are rounded to 6 decimal places.

Use total_tokens as the metered tokens of the conversation. prompt_tokens adds the prompt of every stored message, including the copy that sits on your own question, so it counts each prompt twice and it grows with the history. That is why it can be larger than the total_tokens beside it.

Other endpoints#

GET /api/v1/usage/apibar gives this month's and today's cost per provider for a status bar, and has the same balance caveat. GET /api/v1/usage/daily-ring and GET /api/v1/usage/savings serve the apps and are not described here.

Cost on each call#

The cost of one answer is on the answer itself on the native chat stream: usage.cost and usage.cost_estimated. The /v1 endpoints report tokens only, in usage.