Sessions, context window and billing

Billing

Ward is billed on input tokens, counted before the decision runs, from a prepaid balance. Output is not billed. Sandbox keys (ward_test_…) are never billed.

• Top up from the console (Stripe Checkout). GET /api/v1/billing/balance and GET /api/v1/billing/usage?days=30 show the balance and consumption.
• If the balance does not cover a call, nothing runs and the answer is 402 insufficient_balance with the call's cost and your balance.
• If a decision fails after it was charged, the charge is refunded automatically.
• An Idempotency-Key makes a retried call return the first answer without deciding or billing twice.

Each call's own token count goes to your usage log; the answer itself shows the session meter.

Sessions

session_id groups the calls of one review, chat or case. It is your string (up to 64 characters): a case id, a chat id, a batch id.

• Every session has a context window of 1,000,000 tokens. Each call reserves its tokens in the window; a failed call releases them.
• context on every answer is the meter: window_tokens, used_tokens, remaining_tokens, used_pct, and balance_usd when billed.
• When the window is full the answer is 413 with code: window_full: start a new session_id.
• Ward Ask follow-ups use the same session_id, so questions stay with their result.
• GET /api/v1/sessions/{session_id} lists the decisions of a session.

Per-call limits

See Errors and limits.