Usage & Billing

Tokens

Every metered operation has a fixed cost in tokens, taken from one catalog. That is the same catalog the middleware bills from, the quote endpoint prices from, and the API Reference displays — there is no second table that can drift out of sync with what you are charged.

Costs track what an operation actually consumes on our side. The large majority of the catalog — PDF manipulation, document conversion, extraction, barcodes, templating — is one token a call. A handful cost more: work billed per page, AI-backed analysis, and the few endpoints that pass a third party's charge through to you. Each endpoint's exact cost is on its own reference page, and nothing is metered that is not listed there.

New accounts start on the free beta tier: 500 tokens a month. No card, no trial clock. It is a real allowance meant to be used, not a demo.

Your allowance, and what carries over

Your balance is one pool made of two kinds of tokens, and they behave differently:

Kind	Where it comes from	What happens on the 1st
Monthly allowance	Your plan, refilled automatically.	Reset. Unspent allowance is swept — it does not roll over.
Purchased tokens	Top-ups you paid for.	Carried forward. Purchased tokens never expire.

The allowance is spent first, so purchased tokens are the last thing you draw down and the first thing a refund restores. That ordering exists so a month of light use cannot quietly burn tokens you paid for.

GET /api/account/balance returns the split explicitly — allowanceBalance, purchasedBalance, monthlyReset and allowanceExpiresOnReset — so you never have to infer which half of the number survives the month.

How a call is charged

Tokens are reserved before the operation runs and settled after it:

Reserve. The cost is deducted up front, atomically. If it does not fit, the call is refused with 402 and the work never happens — no half-finished document, no email sent that you then get billed for twice.
Run. The operation executes.
Settle. On success you are charged what it actually cost and any unused part of the reservation is refunded. On failure the whole reservation is refunded — failed calls are not billed.

For per-page operations the reservation is exact whenever the page count can be read from your request. When it cannot, the platform holds a refundable worst case (the per-page rate across the 30-page cap) and refunds the difference once the real page count is known. That hold is what a 402 fires on, which is why quoting first is worth the extra call.

A published pipeline is reserved and billed once, up front — not once per step, and not again for intermediate results. Its steps are metered exactly as the same operations are when you call them directly, including per page. Because a step's document is usually the previous step's output, a per-page step inside a workflow cannot be counted before the run: it is held at the 30-page worst case and the unused hold is refunded when the run finishes.

What every response tells you

Header	Meaning
`X-Tokens-Used`	What this call was charged after settlement — the real figure, not the reservation.
`X-Tokens-Remaining`	Your balance afterwards. On an unmetered account this is the literal string `unlimited`.
`X-Correlation-Id`	The id this call is recorded under, so a header can be matched to a ledger entry.
`X-Billable-Units`	Pages actually processed, on a per-page operation. Present only when the operation is billed per page and the count is known — a missing header never means one page.

Those headers are on the response you already have. You do not need a second request to know your balance after a call.

Price a job before you run it

POST /api/quote prices a job — one call or a whole stack — before you commit. It is free and unmetered, because a pre-quote that costs a token cannot be used for the thing it exists for.

Quote a stacked job

POST /api/quote
{
  "operations": ["ConvertHtmlToPdf", { "operation": "WatermarkPdf", "quantity": 3 }],
  "mode": "pipeline"
}

Three things in the answer are worth reading carefully:

tokens is what you will be charged — but it is null, with minTokens and maxTokens instead, when the job contains a per-page step and you did not say how many pages. A range is honest; one confident number would not be.
holdTokens is what will actually be reserved. affordable and shortfall are judged against this, not against the eventual charge.
mode is not cosmetic. separate prices N independent API calls; pipeline prices one published Orchestrator run. They do not charge identically, so quote the shape you are going to use.

An operation name it does not recognize is refused, never priced at a default. A typo cannot come back as a cheap quote for an expensive call.

Read your own account

Four endpoints take your own API key, are scoped to your account by construction (there is no account id in any path), and are free and unmetered — no cost, no reservation, no usage row. Charging you to read your own bill would be indefensible.

Endpoint	What it answers
`GET /api/account`	Does this exact key authenticate, and which account is it?
`GET /api/account/balance`	What is in the pool, split into allowance and purchased tokens.
`GET /api/account/ledger`	Charges, refunds, top-ups, grants and allowance resets, newest first.
`POST /api/quote`	What a job will cost before you run it.

The ledger

GET /api/account/ledger accepts ?daysBack= (1–365, default 30) and ?limit= (1–500, default 100), and tells you with truncated when the window held more than it returned. Each entry is signed the way a statement reads — delta is negative for tokens out, positive for tokens in — and carries its kind:

`charge`	A billed call.
`refund`	A reservation given back — a failed call, or the unused part of a per-page hold.
`purchase`	A top-up you paid for.
`grant`	Tokens added to your account by us.
`allocation`	The monthly allowance reset.
`event`	A call that moved no tokens — a refused `402`, or a failure already refunded in its own entry. Recorded so the history is complete, with a delta of zero so it cannot skew a total.

windowSummary totals only the entries returned, and is labeled that way on purpose: a window is a slice of your history, never your account balance. The live balance comes back in the same response, from the account record itself.

In the portal

Portal → Usage — the same history in the browser, per operation, with what each call cost.
Portal → Top Up — add purchased tokens, which never expire.
Portal → API Key — the key that spends them.

What we commit to

No hidden credit system. One unit, one published cost per operation, visible on the endpoint's own reference page.
You can see what every call spent — on the response headers, in the portal, and in an API you can read yourself.
You can see what a call will spend before you make it, from the same catalog we bill from.
Failed work is not billed, and a reservation that turns out to be too large is refunded.
Tokens you paid for do not expire.