# Usage and API keys

Use read-only account and key endpoints to show spending and limits in your own integration. Authentication is the same Bearer API key used for inference.

## Account usage

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/usage \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY"
~~~

The response contains:

| Field | Scope |
| --- | --- |
| `usage` | Daily per-model entries for the last 30 days |
| `balance` | Current account balance in SC |
| `total_spent` | Lifetime recorded usage cost in SC |

Daily entries contain `date`, `model`, `requests`, `tokens_in`, `tokens_out`, `tokens_cached`, and `cost_sc`, plus the account ID. Their date range differs from the lifetime total.

This V1 route does not accept `from`, `to`, `days`, or `granularity` filters. Those names must not be inferred from dashboard analytics routes.

## Current key metadata

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/keys/current \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY"
~~~

Metadata includes the key ID, prefix, name, nullable rate and concurrency overrides, balance settings, and creation/last-use/revocation timestamps. It does not return the key secret.

Null overrides are not a promise of unlimited throughput. Account, model, and upstream limits can still apply.

## Key usage

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/keys/current/usage \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY"
~~~

~~~bash
curl --fail-with-body https://api.simplellm.eu/v1/keys/current/usage/daily \
  -H "Authorization: Bearer $SIMPLELLM_API_KEY"
~~~

The aggregate returns `total_requests`, `total_tokens_in`, `total_tokens_out`, and `total_cost_sc`. The daily endpoint returns `{"usage": [...]}` for the last 30 days, with a date and those totals for each entry.

These key summaries do not expose a separate cache counter. Do not manufacture one by subtracting unrelated totals; use the available account/model usage or final inference usage where appropriate.

## Other keys in the account

`GET /v1/keys/` returns `{"api_keys": [...]}`. The trailing slash is part of the listed route.

To read another owned key's usage, use its UUID with `/v1/keys/{keyID}/usage` or `/v1/keys/{keyID}/usage/daily`. The server checks ownership; the key ID is not the API key secret.

## Operational guidance

Create, configure, rotate and revoke keys through the dashboard. The public reference covers only the existing read-only key routes, not administrator or dashboard-session mutations.

Usage recording can finish after a response completes. Avoid treating a single immediate poll as proof that a request was free, and do not poll every stream chunk.

For cost calculations, distinguish provider prompt totals from separately shown cache counts as explained in [Tokens, cache and billing](/docs/billing.html).