Billing, quotas & credits

Plans and what you pay for

You pay for two things (SPEC-15): turns (successful /v1/respond calls) and active relationships (a user your agent actually talked to in a calendar month). Memory storage is free, forever. GET /v1/billing/plans returns the catalogue; upgrades apply immediately with day-prorated fees and quotas; downgrades take effect at period end.

Quotas, overage, hard caps

Each plan includes monthly turn and relationship quotas. Your overage policy decides what happens beyond them: allow_overage (default on paid plans — extra usage is billed next month at the plan's overage rates) or hard_cap (requests beyond quota fail with 429 quota_exhausted). The Free tier is always hard-capped.

Every turn-consuming response carries X-Quota-Turns-Used, X-Quota-Turns-Limit, X-Quota-Active-Relationships-* and X-Quota-Resets-At headers, so your integration can budget without extra calls.

Usage alerts

POST /v1/billing/alerts fires when usage crosses a threshold (e.g. 80% of turns) — by email and, if enabled, as a quota.threshold_reached webhook. Alerts fire at most once per month each.

Credits

Support or promotional credits are granted as Stripe customer balance and applied to your next invoice automatically. GET /v1/billing/credits shows the live available credit and the history of applied ones.