Usage & cost

Every request to the Syntic API is measured in tokens, and every token is paid for in one of two ways: from your organization’s plan allowance, or from its usage-credit wallet. This page explains how usage is counted, the three windows the plan is enforced over, how a credit-paid request is priced, and how to keep an eye on all of it from the Console and from your own code.

How a request is counted

Each successful response carries a usage object:

"usage": {
  "prompt_tokens": 1840,
  "completion_tokens": 312,
  "total_tokens": 2152,
  "prompt_tokens_details": { "cached_tokens": 1536 }
}

For streamed responses, usage arrives on the final chunk before the [DONE] line. Only successful requests count towards the plan windows; requests that fail before or at the model do not.

The three plan windows

Your plan’s token allowance is checked over three windows at once. A request is paid by the plan only if all three still have room.

Worked example for a Pro organization (5,000,000 tokens a month):

The weekly and session windows exist to stop one burst, such as a runaway loop, from eating the whole month in an afternoon. Normal steady use stays well inside them. Enterprise plans have no cap in any window.

See Billing & credits for each plan’s allowance.

What happens when a window is full

1. If usage credits are turned on, the monthly spend limit has room and the wallet balance covers the estimated cost of the request, the request goes ahead and is paid from credits.
2. Otherwise it is refused with 402 quota_exhausted.

Each successful response tells you which way it went:

A refused request looks like this:

{
  "error": {
    "type": "insufficient_quota",
    "code": "quota_exhausted",
    "message": "You've hit your weekly usage limit. ...",
    "param": null,
    "request_id": "req_6f1c2a9e0b7d4c3a8e5f1b2d",
    "limit": "weekly",
    "resets_at": "2026-10-13T12:00:00.000Z",
    "upgrade_url": "https://syntic.ai/pricing",
    "add_credit_url": "https://syntic.ai/agents/billing#api-topup"
  }
}

When more than one plan window is full, limit names the one that reopens last, because that is when the plan can pay again.

Track usage from your code

Read the usage object and the billing header on every response, and log them alongside your own request identifiers.

curl -sS -D headers.txt https://app.syntic.ai/v1/chat/completions \
  -H "Authorization: Bearer $SYNTIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"model": "Amara S1.2", "stream": false,
       "messages": [{"role": "user", "content": "Write a haiku about invoices."}]}' \
  | jq '.usage'
 
grep -i '^x-syntic-' headers.txt

import os
from openai import OpenAI
 
client = OpenAI(base_url="https://app.syntic.ai/v1", api_key=os.environ["SYNTIC_API_KEY"])
 
raw = client.chat.completions.with_raw_response.create(
    model="Amara S1.2",
    stream=False,
    messages=[{"role": "user", "content": "Write a haiku about invoices."}],
)
completion = raw.parse()
 
print("paid by:", raw.headers.get("x-syntic-billing-source"))
print("request:", raw.headers.get("x-syntic-request-id"))
print("tokens: ", completion.usage.total_tokens)

import OpenAI from 'openai'
 
const client = new OpenAI({ baseURL: 'https://app.syntic.ai/v1', apiKey: process.env.SYNTIC_API_KEY })
 
const { data, response } = await client.chat.completions
  .create({
    model: 'Amara S1.2',
    stream: false,
    messages: [{ role: 'user', content: 'Write a haiku about invoices.' }],
  })
  .withResponse()
 
console.log('paid by:', response.headers.get('x-syntic-billing-source'))
console.log('request:', response.headers.get('x-syntic-request-id'))
console.log('tokens: ', data.usage.total_tokens)

For handling 402 gracefully, with back-off until resets_at, see Handle usage limits.

How cost is calculated

Requests paid by the plan cost nothing beyond the plan itself.

Requests paid by usage credits are charged at the model’s per-million-token rates, with three parts priced separately:

cost = (prompt_tokens − cached_tokens) × input rate
     +  cached_tokens                  × cached-input rate
     +  completion_tokens              × output rate

Worked example on Amara S1.2 ($2.50 input, $0.40 cached input, $12.00 output per million tokens), using the sample usage object shown earlier:

Current rates for every model are on Pricing.

What the Console shows

Settings → Usage

Settings → API Access

A compact view of This month’s usage against the plan allowance and the API credit balance, alongside connected Syntic Code sessions.

Settings → API Keys

Each key’s Last used time and number of uses, handy for spotting a key that has gone quiet or one that is suddenly busy.

Per-member and per-group spend limits

Administrators can cap how much of the organization’s credit spend a single member may use each month, on the Usage page under Spend limits.

• Member limit: set on one member. It wins over any group limit.
• Group limit: set on a group and inherited by each of its members who has no limit of their own. It caps each member’s spend separately, not the group’s combined spend. The Console marks inherited limits.
• Multi-group spend limit: when a member belongs to several groups with limits, choose whether the higher or lower group limit applies.
• Unlimited: removing a limit sets it back to no cap.

Member limits count only spend paid by credits; tokens covered by the plan do not count against them. A member at their limit gets 402 quota_exhausted with limit: "spend_limit" on every API request until the next month or until an administrator raises the limit, even if the organization’s own limit still has room.

Two related switches under Spending defaults:

• Member analytics lets members see a breakdown of their own usage.
• Allow usage requests lets a member at their limit ask for more. Administrators approve or deny requests in the Usage requests list.

Related

• Billing & credits
• Pricing
• Limits
• Handle usage limits