API key balance and usage
Read balance, usage totals and the current API key limits.
Last updated on
These read-only endpoints use the same platform API key as model requests. Keep it on your server and send it as Authorization: Bearer ${API_KEY}. The workspace is taken from the verified key; X-Org-Id cannot select another workspace.
GET /v1/balance
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/balance" \
-H "Authorization: Bearer ${API_KEY}"The 200 response is:
type Balance = {
availableBalance: number;
currency: string;
reservedBalance: number;
};availableBalance is the balance available after the current reservation amount; reservedBalance is the amount currently reserved. The currency is returned by the deployment. In the provod.ai deployment it is RUB; do not convert it to another currency.
Customer prices
Current provod.ai prices, rather than the provider's internal costs, are published in the model catalog. For programmatic access, use GET https://api.provod.ai/api/models.
A text model in the catalog may include:
promptPricePer1mTokens— input-token price per 1 million tokens;completionPricePer1mTokens— output-token price per 1 million tokens;cacheReadPricePer1mTokens— cache-read price;cacheWritePricePer1mTokens,cacheWrite5mPricePer1mTokens,cacheWrite1hPricePer1mTokens— cache-write prices when configured;currency— the currency for these prices.
When a price is null, no separate price for that category is published. Do not replace it with a provider price or convert it yourself.
GET /v1/usage
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/usage?range=30d" \
-H "Authorization: Bearer ${API_KEY}"range is optional. The default is 30d; allowed values are 1d, 7d, 30d, 365d and all. An invalid value returns 400. The response has this shape:
type Usage = {
range: "1d" | "7d" | "30d" | "365d" | "all";
from: string; to: string;
summary: Summary;
daily: DailyPoint[];
models: ModelBreakdown[];
};Summary contains numeric requestCount, successfulRequestCount, failedRequestCount, promptTokens, completionTokens, cacheReadTokens, cacheWriteTokens, cacheWrite5mTokens, cacheWrite1hTokens, totalTokens, estimatedCost, chargedAmount and averageDurationMs. DailyPoint contains date, requestCount, token counters, estimatedCost and chargedAmount. ModelBreakdown contains model, requestCount, token counters, estimatedCost and chargedAmount.
The daily array contains UTC days in the selected period, including days with no activity. Empty totals and arrays follow the same typed response; no sample values are implied. Costs are numeric amounts in the returned billing currency. estimatedCost is an estimate recorded for the request; chargedAmount is the amount recorded as charged by the usage read model. Do not treat either field as a supplier invoice.
All results are limited to the bearer key. Other keys and workspace-wide key breakdowns are not returned. The endpoint does not provide request-by-request pagination.
GET /v1/key — current key information
curl --fail-with-body --silent --show-error \
"https://api.provod.ai/v1/key" \
-H "Authorization: Bearer ${API_KEY}"This response is wrapped in { "data": ... } and contains:
type CurrentKey = {
label: string; limit: number | null; limit_reset: string | null;
limit_remaining: number | null; usage: number; usage_daily: number;
usage_weekly: number; usage_monthly: number;
byok_usage: number; byok_usage_daily: number; byok_usage_weekly: number; byok_usage_monthly: number;
include_byok_in_limit: boolean; is_free_tier: boolean;
free_model_daily_requests: { used: number; limit: number; remaining: number };
is_management_key: boolean; is_provisioning_key: boolean; creator_user_id: string;
organization_id: string | null; workspace_id: string | null; expires_at: string | null;
allowed_data_regions: string[] | null;
rate_limit: { interval: string; requests: number; note: string } | null;
};limit and limit_remaining describe the active key spend limit when one exists; limit_reset is its period (day, week or month). usage* are usage amounts recorded for this key in the billing currency.
Important response details
free_model_daily_requestscurrently returns{ used: 0, limit: 0, remaining: 0 }. This compatibility response does not claim a free quota.is_free_tierisfalse;byok_usage*are0;include_byok_in_limitandis_provisioning_keyarefalse;allowed_data_regions,organization_idandrate_limitarenull. These values do not announce unlisted quotas, BYOK accounting or regional availability.total_cost-style values from the generation endpoint and these usage values have distinct meanings. Use the field descriptions above rather than comparing them as supplier charges.
Management keys can identify themselves through /v1/key and read authorized generation metadata through /v1/generation. They cannot use /v1/balance or /v1/usage, and cannot run inference. Use /v1/credits and /v1/activity for management billing reads; see the permission matrix.