# API key balance and usage

Source: https://provod.ai/en/docs/api-key-usage

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

```bash
curl --fail-with-body --silent --show-error \
  "https://api.provod.ai/v1/balance" \
  -H "Authorization: Bearer ${API_KEY}"
```

The `200` response is:

```typescript
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](https://provod.ai/en/models). 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

```bash
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:

```typescript
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

```bash
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:

```typescript
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_requests` currently returns `{ used: 0, limit: 0, remaining: 0 }`. This compatibility response does not claim a free quota.
* `is_free_tier` is `false`; `byok_usage*` are `0`; `include_byok_in_limit` and `is_provisioning_key` are `false`; `allowed_data_regions`, `organization_id` and `rate_limit` are `null`. 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](/en/docs/management-keys).

## Related articles

* [Management keys and workspace billing](/en/docs/management-keys)
* [Generation metadata](/en/docs/generation-metadata)
* [API authentication](/en/docs/authentication)

## Troubleshooting


**The key response shows zero free-model requests**


This compatibility response does not currently publish a measured free-model quota. Do not interpret the zero tuple as a promise of free access; use the current model catalog and account balance.


**Usage differs from a model price calculation**


`chargedAmount` is the customer-facing amount recorded by Usage. Catalog prices describe current rates; they do not reconstruct a historical settled charge for a request.
