Billing & credits

API traffic is paid for in two layers:

1. The plan. Your organization’s subscription includes a token allowance, enforced over monthly, weekly and 5-hour windows.
2. Usage credits. An optional prepaid US-dollar wallet that pays, at per-model rates, for requests the plan cannot cover.

Requests always try the plan first. Credits are only touched once a plan window is full, and only if you have turned them on. This page covers plans, the credit wallet, buying credits, auto-reload and the spend limits that keep it all bounded.

Plans

Each plan includes a monthly token allowance shared by everyone in the organization. Prices are on syntic.ai/pricing.

How the windows work is explained in Usage & cost. Some models are only offered on certain plans; a request for a model your plan does not include is served by the default model instead, and the response carries an x-syntic-model-downgraded header. See Models.

Usage credits

Usage credits keep your API running after the plan allowance is spent, at a cost you control.

A request is paid from credits only when all of these hold:

• a plan window is full for this request;
• credits are turned on for the organization;
• the organization has not reached its monthly spend limit;
• the member who owns the key has not reached their own spend limit, if one is set;
• the wallet balance covers a conservative estimate of what the request could cost.

If any condition fails, the API returns 402 quota_exhausted and names the reason in limit. See the table in Usage & cost.

Settings

Credits are managed in Settings → Billing, in the Usage credits section. Only owners and administrators can change them; every member can see them.

The section also shows the current balance and how much credit has been spent this month.

Buy credits

Preset packs

Custom amounts

Auto-reload

Auto-reload keeps the wallet from running dry in the middle of a busy day.

How it behaves

• The platform checks wallets with auto-reload turned on at regular intervals.
• When the balance is at or below the trigger, your saved default card is charged the difference between the balance and the target, so the balance returns to the target. With a $5 trigger, $15 target and $3.20 left, the charge is $11.80.
• The wallet is credited once the charge succeeds, just like a manual top-up.
• Charges under $0.50 are skipped.

Because reloads happen on a schedule rather than on every request, a large burst can still empty the wallet between checks. Leave enough headroom between the trigger and your busiest few minutes of spend.

Spend limits

Spend limits only ever restrict credit spend; plan usage is never blocked by them.

All spend limits start afresh when a new calendar month begins (UTC midnight). Details of group and member limits are in Usage & cost.

React to billing errors in code

Your code cannot change billing settings, but it can tell the difference between “wait” and “a person needs to act”:

import os
import requests
 
resp = requests.post(
    "https://app.syntic.ai/v1/chat/completions",
    headers={"Authorization": f"Bearer {os.environ['SYNTIC_API_KEY']}"},
    json={
        "model": "Amara Deep",
        "stream": False,
        "messages": [{"role": "user", "content": "Draft a reply to this refund request."}],
    },
    timeout=120,
)
 
if resp.status_code == 402:
    err = resp.json()
    if err["limit"] in ("monthly", "weekly", "session"):
        print("Plan window full; it reopens at", err["resets_at"])
    elif err["limit"] in ("spend_limit", "no_credits"):
        print("A billing admin needs to act:", err["add_credit_url"])
    else:  # "unavailable"
        print("Usage check failed; retry shortly")
else:
    resp.raise_for_status()
    print(resp.headers["x-syntic-billing-source"], resp.json()["usage"])

const resp = await fetch('https://app.syntic.ai/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.SYNTIC_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'Amara Deep',
    stream: false,
    messages: [{ role: 'user', content: 'Draft a reply to this refund request.' }],
  }),
})
 
if (resp.status === 402) {
  const err = await resp.json()
  if (['monthly', 'weekly', 'session'].includes(err.limit)) {
    console.log('Plan window full; it reopens at', err.resets_at)
  } else if (['spend_limit', 'no_credits'].includes(err.limit)) {
    console.log('A billing admin needs to act:', err.add_credit_url)
  } else {
    console.log('Usage check failed; retry shortly')
  }
} else if (resp.ok) {
  const body = await resp.json()
  console.log(resp.headers.get('x-syntic-billing-source'), body.usage)
}

A fuller pattern, with retries and alerting, is in Handle usage limits.

Who can do what

Adding and removing payment methods is recorded in the audit log.

Related

• Usage & cost
• Pricing
• Handle usage limits
• Errors