Get token balance

Return this key's token limit, usage, remaining balance, and reset time.

← All Meta tools endpoints · Capability overview

GET/v1/meta-tools/token-balance

https://api.vee3.io/v1/meta-tools/token-balance

0 tokens

Return this key's token limit, usage, remaining balance, and reset time.

Authorization

Send your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

MCP

The same capability is available as an MCP tool on Vee3 hosted MCP.

Tool name

meta-tools.token_balance

Parameters0 fields

Response7 fields

billing_planstring

Current billing plan id (free, starter, pro, scale).

monthly_token_allowanceinteger

Token limit for this key in the current billing period. A project key whose project has a spend cap reports that cap. Otherwise this is the account's monthly allowance.

tokens_usedinteger

Tokens already counted against that limit in the current billing period.

tokens_remaininginteger

Tokens left before that limit is reached.

billing_period_startstring

ISO 8601 start of the current billing period.

billing_period_endstring

ISO 8601 end of the current billing period.

billing_period_resets_atstring

ISO 8601 timestamp when the token allowance resets (same as period end).

HTTP errors: unauthorized, payment_required

Example request

Python

import requests

url = "https://api.vee3.io/v1/meta-tools/token-balance"
headers = {
    "Authorization": "Bearer YOUR_API_KEY",
}
params = {

}

response = requests.get(url, headers=headers, params=params)
response.raise_for_status()
data = response.json()
print(data)

Example responses1 example

200Token allowance and usage for a free-plan account mid-period.

free_plan_balance.json

{
  "billing_plan": "free",
  "monthly_token_allowance": 1000,
  "tokens_used": 120,
  "tokens_remaining": 880,
  "billing_period_start": "2026-05-01T00:00:00Z",
  "billing_period_end": "2026-06-01T00:00:00Z",
  "billing_period_resets_at": "2026-06-01T00:00:00Z"
}