Prima API
Usage
GET /usage. This tenant's metering for the current period, and the credit balance when the deployment enforces credits.
Live Built and working today on the surface this card describes.
What it does
Reports this tenant's metering for the current period, per surface, plus the credit balance when the deployment enforces credits.
chat is metered in tokens and embeddings in requests. Each carries included, used, overage and spend_cap.
The credit block is present only when the deployment enforces credits. When it is absent, no balance is being debited on that deployment. Render that, never a zero.
balance_micro is the value of record, in micro-CHF. It can be negative, down to the tenant's credit limit. balance_chf is a display string. The figure to show as available is total_sparks, which is allowance plus balance plus any overdraft.
Inputs and outputs
| Request | GET https://api.prima.li/api/prima/v1/usage, with the X-API-Key header. |
|---|---|
| Response | tenant_id, period_start, period_end, a chat block, an embeddings block, and a credit block when credits are enforced. |
| Credit block | currency, balance_micro, balance_chf, balance_sparks, spendable_sparks, allowance_micro, allowance_sparks, allowance_expires_at, total_micro, total_sparks, unit, credit_limit_micro, spendable_micro, exists. |
exists: false | No ledger row for this tenant yet. |
| Per-alias or per-day breakdown |
Configuration
| Credential | X-API-Key only. A Labs session token is not accepted here. One the deployment can verify is refused with 503 identity_provider_unavailable and a Retry-After header, because the introspection half of that seam is not built; one it cannot verify is a 401 invalid_api_key, and the wiki records that the standalone service cannot yet verify a Labs JWT. Not measured on api.prima.li. |
|---|---|
| Period | Not selectable. The response reports the current period only, with its start and end. |
Limits
- There is no per-alias and no per-day usage endpoint. The meter records the alias and the timestamp on every event; nothing exposes those rows.
- Reasoning tokens are counted into
usedand are not reported separately, so a cost estimate based on visible output length will be wrong. allowance_*is zero for every prepaid tenant. Sparks figures are floored.
Example
read the metering
curl https://api.prima.li/api/prima/v1/usage \
-H "X-API-Key: $PRIMA_API_KEY"Source of truth
prima/prima/models/meter.py (`to_dict`: the `chat` and `embeddings` blocks, their units, `included`, `used`, `overage`, `spend_cap`)prima/prima/credits.py (`get_account_state`: every field of the credit block, the floored Sparks, `exists`)prima/prima/seams/identity.py (`_resolve_jwt`: a Labs token with an unknown `kid` or a failed signature is undecodable and, with no key, a 401 `invalid_api_key`)prima/prima/auth/sessions.py (`_unavailable()`: the 503 `identity_provider_unavailable` a verified Labs token reaches)philosophers_stone/platform/primaapi.md § Open items (a Labs JWT cannot yet be verified by the standalone service)philosophers_stone/platform/primaapi.md § Other measured facts (reasoning tokens counted and invisible)philosophers_stone/platform/primaapi.md § Open items (no per-alias or per-day usage endpoint)