Docs
Key groups
Give each of your clients its own API keys, keep them together in a group, read what each client and each key spent over any period, and cap what each client can spend in a month. One account, one balance.
A group is a folder of API keys in your account, for example one per client: CID000001, CID000002. A key in a group calls the API like any other key, and a group has no balance, top-ups or login of its own; it can have a monthly spending limit over all of its keys. A key is in one group or in none.
Set up groups in three steps
- Create a group. On the API Keys page, choose New group and name it after the client.
- Put keys in it. Choose New key on the group's heading to create a key inside it. To file a key you already have, open its menu and choose Move to group.
- Read the figures. The API Keys page shows what each key spent this calendar month and each group's total. The Usage page shows the same keys under their groups for today, the last 7 or 30 days, this month, last month, or days you pick, up to 90 of them.
Read a month and export it
On the Usage page, choose Last month (or This month, or Custom for days you pick) at the top. Under By API key, each group's heading shows its cost and calls. The group menu at the top narrows the whole page to one group: its figures, chart, models and calls. Export CSV downloads what the page shows, the same range and the same group, by key or by day.
By key, the file has one row per key and group, named like kunavo-cost-by-key_2026-10-01_2026-10-31.csv. It lists every key that made calls in the range, revoked ones included, under the group each call was made in, and every active key with no calls in the group it is in now, at 0, so each client's list of keys is complete. Groups come in the order the dashboard lists them, each group's keys from most to least expensive, and keys in no group last. By day, the file has a date column first and one row for each day a key made calls in a group.
| Column | What it holds |
|---|---|
group | The group the calls were made in; empty for calls made in no group. A group deleted since has (deleted) after its name. |
key_name | The key's name. |
key_prefix | The start of the key, as the dashboard shows it. Never the whole key. |
key_status | active or revoked. |
calls | Calls made with the key in the range. |
errors | Those of the calls that failed. A failed call costs nothing. |
input_tokens | Input tokens, cache reads and cache writes included. |
output_ | Output tokens. |
cached_ | Of the input tokens, those read from the prompt cache. |
cache_ | Of the input tokens, those written to the prompt cache. |
cost_usd | What the calls were charged, in US dollars, to eight decimal places. |
=, +, - or @ is written with a leading apostrophe, so a spreadsheet shows it as text instead of running it as a formula.Cap what each group spends in a month
Open a group's menu on the API Keys page and choose Set monthly limit. The limit counts what all of the group's keys spend together in a calendar month (UTC): the calls made while each key was in the group. A request that would take the group past it is refused with a 402 and nothing is charged for it. Leave the field blank for no limit, or set 0 to pause every key in the group without revoking any.
A key's own monthly limit still applies, and whichever limit is reached first refuses the request. The group's heading shows its month against the limit, with Limit reached once requests are being refused, and Paused when the limit is 0.
Kunavo emails your account's address when a group, or a key with a limit of its own, has used 80% of its monthly limit, and again when requests start being refused under it: at most one email of each a month for each limit.
How the figures are counted
- Cost is what was charged. Each call's cost is the amount taken from your balance when it finished. A failed call costs nothing.
- Months and days are UTC. This month starts at 00:00 UTC on the 1st. In Yangon (UTC+6:30), for example, October ends at 06:30 on November 1, local time. The Usage page prints the dates of the range it shows.
- A call counts in the group its key was in when the call was made. Move a key to another group and only its calls from then on count there; its earlier calls stay where they were. So a group's month on the API Keys page can differ from the sum of the keys listed under it now.
- A revoked key stays in its group. What it spent before it was revoked still counts in that group's totals and appears in the export.
- A deleted group keeps its calls. They stay under its name, marked as deleted, on the Usage page and in the export, and the name can be used again for a new group.
- Three places, one figure. For one calendar month, a group's total on the API Keys page, its total under This month on the Usage page, and the sum of its rows in the CSV are the same, to the cent.
Questions
- Does each group have its own balance? No. All groups draw on your account's one balance. To cap what one client can spend, set a monthly limit on its group, or on each of its keys.
- Can my clients log in to see their usage? No. Groups are visible only to you. A key can read its own usage with GET /v1/usage, which does not show its group. When its group has a monthly limit,
GET /v1/balanceshows the key that limit and what the whole group has spent this month, but not the group's name. - What happens when I delete a group? You choose: its keys keep working, ungrouped from then on, or they are revoked with the group. Either way, the calls they made stay under the group's name.
- What if a key moves from one client to another? Move it to the other client's group: its calls count there from then on, and its earlier calls stay with the first client.
- Can I read a range other than these? Yes: choose Custom on the Usage page and pick up to 90 days. For a program, GET /v1/usage returns one key's cost per day over the same span.
To create, group, cap and revoke a client’s keys from your own tools instead of by hand, use the management API. Its keys are a separate credential, and they work only on that API.