Get token balance

Return monthly token allowance, 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 monthly token allowance, 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

get_token_balance

Parameters0 fields

Response7 fields

billing_planstring

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

monthly_token_allowanceinteger

Total tokens included in the current billing period.

tokens_usedinteger

Tokens consumed in the current billing period.

tokens_remaininginteger

Tokens left before quota is exhausted.

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 = {
    "url": "https://example.com"
}

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"
}