GET /usage for your plan, balance, forecast and a breakdown of your spend, and GET /usage/transactions for the individual metered charges behind it.
Check your balance and spend
GET /usage returns your plan, remaining credit balance and where it came from, a forecast of whether the balance lasts until your billing cycle ends, and your spend over a window (the current billing cycle unless you pass start_time/end_time) broken down by operation, by day, and by the chats and scheduled tasks that spent the most.
- cURL
- SDK (TypeScript)
- MCP (agent)
by_day trimmed to three days):
object
Your current plan:
name, status, is_paid, on_trial, trial_ends_at, renews_at, and its price (in cents, per interval) and currency. has_payment_method says whether a card is on file.object
balance is what’s left. plan_credits, top_up_credits and bonus_credits split it by where it came from: a paid plan’s credits expire when the billing cycle renews, top-ups and bonuses don’t. monthly_allowance is what the plan grants each month, limit_reached is true once the balance hits zero, and auto_top_up says whether the account refills itself.object
Spend between
period_start (inclusive) and period_end (exclusive): total_credits, today_credits (always today, whatever the window), by_operation[], by_day[] (every day of the window up to today, in time_zone, zero days included), and by_chat[] — the 10 chats and scheduled tasks that spent the most, with every run of a task summed under the task. by_chat lists only chats you can read and leaves out charges not tied to a chat (API calls, web operations), so it can sum to less than total_credits.object
The last 7 days’ spend rate (or since the billing cycle began, if sooner):
burn_rate_per_day, the moment the balance runs_out_at at that rate, the projected_balance_at_period_end of the billing cycle, and will_run_out before it renews.start_time (inclusive) and end_time (exclusive) are ISO 8601 timestamps. Omit them for the current billing cycle, or the calendar month without a subscription; for the previous cycle, pass the current period_start as end_time and one cycle earlier as start_time. A window can’t exceed 366 days. Write times in UTC (Z) or URL-encode the + of an offset, which a query string otherwise reads as a space. The window only moves spend: credits, plan and forecast always describe the current billing cycle. Days are cut in your time zone, else the account’s.
See individual charges
GET /usage/transactions lists each metered charge so you can attribute spend precisely.
object: "list", data, has_more) — paginate it with limit and starting_after like any other list endpoint.
List plans
GET /plans returns the pricing catalog as the pricing page sells it — one entry per plan and billing interval — read from the same records that bill the account, so you never have to hardcode a price or a limit.
array
Each credit tier of the plan, smallest first: its
credits and its price in the smallest currency unit (cents) per interval. The tier this account is subscribed to has current: true.string[]
What the plan unlocks: any of
custom_domain, team_invitations, webhooks, api_access and remove_branding.array
Every quota by
name — active_products, sites, storage_megabytes, marketing_emails_per_day, voice_calls_per_day and more — with its value on this plan. null means unlimited.has_more: false). Pair it with GET /usage, whose plan says which plan the account is on now.
What consumes credits
Operations that run AI or external compute are metered:
Reading and managing your own data (products, orders, customers, webhooks) is not AI-metered.
AI media pricing
Media generation is priced in USD per unit and converted to credits. Pick the cheapest model that meets your quality bar — the default is the most economical.Images (per megapixel, unless noted)
Video (per second, unless noted)
Audio / TTS (per 1,000 characters)
Run
GET /images/models, GET /videos/models, and GET /audio/models for the live model list — new models appear there before this table is updated.Next steps
Conventions
List envelopes and pagination apply to transactions too.
Errors
How balance and rate issues surface.
MCP & agents
Tasks and agent work are the main credit consumers.
API reference
Full usage and media generation schemas.