Monitoring usage & credits

Transactional debits credits as you use the platform. This page is how to read them, alert on them, and decide what to do when you're running low.

The two counters

Every account has two independent counters, each with a monthly grant from your plan plus any one-off top-ups you've purchased:

Counter	Debited by
Generation credits	Every successful `POST /v1/generate` call (and `generate_pdf` via MCP). One credit per call. Failed renders refund automatically.
AI credits	Every assistant turn in the editor. Debited proportionally to tokens consumed (input + output + cache reads/writes).

The dashboard's Statistics view shows both gauges with used / included / topUp / remaining. The top-of-page banner turns amber at 80% used and red at 100%.

Where to look

Statistics → top of page — the two gauges, current period
Statistics → consumption chart — 30-day timeline, with error count
Statistics → recent calls — the last 10 API calls (status, route, latency, key used)
Billing → subscription — plan, current period end, top-up history

Reading the chart

The 30-day chart shows total calls and errors per day. Two patterns to watch:

Steady baseline + sudden spike — a job loop with a bug ("regenerate for all customers"). Pause and investigate.
Slow upward drift — your business is growing. Plan an upgrade before the cap.

The error rate is shown on the same chart. A green ~99%+ success rate is normal. Persistent 5xx during render time usually means Gotenberg saturation on our side — check status.

What happens at zero

POST /v1/generate returns 402 quota_exceeded when generation credits are at zero:

{
  "error": "quota_exceeded",
  "type": "generation",
  "message": "Generation credits exhausted. Upgrade or top up to continue."
}

The AI assistant returns the same 402 (with "type": "ai") when AI credits run out. The editor surfaces a CTA — the API itself just returns the error so your code can branch on it.

Setting alerts in your own infra

We don't push email or webhooks for credit thresholds today. Two ways to monitor from your side:

Pull-based — `GET /v1/me`

Poll /v1/me from a cron (every few hours is plenty) and alert when usage.generation.remaining falls below a threshold:

curl -s -H "x-api-token: $TRANSACTIONAL_API_TOKEN" \
  https://api.transactional.dev/v1/me \
  | jq '.usage.generation.remaining'

In Python:

import os, urllib.request, json

req = urllib.request.Request(
    "https://api.transactional.dev/v1/me",
    headers={"x-api-token": os.environ["TRANSACTIONAL_API_TOKEN"]},
)
with urllib.request.urlopen(req) as r:
    data = json.loads(r.read())

if data["usage"]["generation"]["remaining"] < 100:
    send_pager_alert("Transactional generation credits below 100")

Reactive — branch on the error

Wrap your /v1/generate calls. When you see quota_exceeded, page the team:

try {
  await generatePdf({documentId, variables})
} catch (e) {
  if ((e as TransactionalError).code === 'quota_exceeded') {
    sentry.captureMessage('Out of Transactional credits', {level: 'error'})
    throw e
  }
  throw e
}

This is the simpler approach but it catches you at zero — by then your customers are seeing failures.

Top up vs. upgrade

Situation	What to do
You hit zero once, end of a busy month	Buy a top-up pack. They never expire.
You're hitting zero every month	Upgrade the plan. The monthly grant is cheaper per credit than top-ups.
You expect a one-off spike (campaign, end-of-quarter invoices)	Top up. Easier to model the cost.
You're growing 20%+ month over month	Upgrade — you'll cross the next tier soon anyway.

Buy from Billing → top-up (one-off) or Billing → change plan (subscription).

The API Keys page shows a 7-day usage sparkline per key. If you've issued multiple tokens (dev / staging / prod), this is how you spot the one that's burning credits. Each call also records the apiKeyId in the audit log — surfaced on Statistics → recent calls.