Balance and usage
Reference for GET /v1/balance and GET /v1/usage: pack credits, free tier, reservations and daily usage by document type, with examples.
Two read-only endpoints to find out how many credits you have left and what you spent them on. Neither spends credits.
| Method and route | What it does |
|---|---|
GET /v1/balance | Current account balance. |
GET /v1/usage | Usage aggregated by day, document type and endpoint. |
Prices and charging rules in Credits and billing and on the pricing page.
GET /v1/balance
curl https://api.constaia.com/v1/balance \
-H "Authorization: Bearer $CONSTAIA_API_KEY"{
"object": "balance",
"credits_available": 1000,
"credits_reserved": 2,
"free_tier_remaining": 118.4,
"credits_spendable": 1118.4,
"free_tier_resets_at": "2026-10-01T00:00:00.000Z"
}| Field | Description |
|---|---|
credits_available | Credits from purchased packs that you can spend. It does not include the free tier. |
credits_reserved | Credits reserved by analyses in progress. They are charged when the analysis finishes according to the real page count, and released if it fails. |
free_tier_remaining | What is left of this month's free tier (150 credits per month). |
credits_spendable | What you can spend right now: credits_available + free_tier_remaining. |
free_tier_resets_at | When the free tier renews: the 1st of each month at 00:00 UTC. Unused credits do not roll over. |
What you can spend right now is credits_spendable (credits_available + free_tier_remaining). The free tier is consumed first and then the packs, oldest first. Values can have decimals because classify costs 0.2 credits.
The balance belongs to the account: it returns the same with a test key as with a live key. Test keys do not spend credits.
If the balance drops below the threshold you set in the dashboard, you receive the credits.low webhook (live mode only, once until you top up).
GET /v1/usage
| Parameter | Format | Default |
|---|---|---|
from | YYYY-MM-DD | 29 days ago (30 days counting today). |
to | YYYY-MM-DD | Today. |
A wrong date format returns 422 invalid_parameter. Usage covers only the key's mode: with a test key you see test usage; with a live key, real usage.
curl -G https://api.constaia.com/v1/usage \
-H "Authorization: Bearer $CONSTAIA_API_KEY" \
-d from=2026-09-01 -d to=2026-09-30{
"object": "usage",
"from": "2026-09-01",
"to": "2026-09-30",
"livemode": true,
"data": [
{ "date": "2026-09-28", "type": "es_dni", "kind": "analysis", "livemode": true, "count": 12, "pages": 14, "credits": 12 },
{ "date": "2026-09-28", "type": "invoice", "kind": "classification", "livemode": true, "count": 5, "pages": 7, "credits": 1 },
{ "date": "2026-09-29", "type": "payment_receipt", "kind": "analysis", "livemode": true, "count": 3, "pages": 3, "credits": 3 }
],
"totals": { "count": 20, "pages": 24, "credits": 16 }
}| Field | Description |
|---|---|
from, to | Range applied. |
livemode | Mode of the key used. |
data[] | One row per day, document type and kind, sorted by date. |
data[].date | Day (YYYY-MM-DD). |
data[].type | Detected document type. |
data[].kind | analysis (analyze and batches) or classification (classify). |
data[].count | Number of documents. |
data[].pages | Pages processed. |
data[].credits | Credits charged. 0 in test mode. |
totals | Sum of count, pages and credits over the range. |
Failed analyses are not charged. Details in Credits and billing.
Example: check the balance before a batch
import { Constaia } from "@constaia/sdk";
const constaia = new Constaia();
const balance = await constaia.balance();
const spendable = balance.credits_available + balance.free_tier_remaining;
const needed = 80; // e.g. 80 documents of up to 2 pages
if (constaia.livemode && spendable < needed) {
throw new Error(`Not enough credits: ${spendable} available, ${needed} needed`);
}
const usage = await constaia.usage({ from: "2026-09-01", to: "2026-09-30" });
console.log(`September: ${usage.totals.count} documents, ${usage.totals.credits} credits`);Next steps
GET /v1/document-types
Reference for GET /v1/document-types: the public catalogue of document types with fields, JSON Schema, validators and applicable checks, no API key needed.
Webhook endpoints
Reference for /v1/webhook-endpoints: create, list, retrieve and delete the URLs that receive Constaia events, with their whsec_ secret and mode.