Control and safety

Usage and limits

Plans and their quotas, how to read where your company stands, your own spend cap, and how to tell a short throttle from a wall that needs a plan change.

Every company is on a plan. The plan sets quotas — how many agents, runs and tokens the company can use — and you can add a spend cap of your own on top. When a limit is reached, the API tells you which one, and whether it clears in seconds, at the next reset, or only with a different plan.

Plans

The current plans, as GET /api/v1/public/plans answered on 2026-10-19. That call needs no key; read it for today's numbers rather than copying this table.

	Free	Starter	Pro	Enterprise
Price (USD)	0	20 / month	99 / month	1,999 / month
Agents	2	3	20	200
Teams (`max_teams`)	1	1	5	40
Runs per month	300	3,000	15,000	200,000
Tokens per day	90,000	750,000	3,333,333	no daily limit
Tokens per month	2,700,000	22,500,000	100,000,000	2,000,000,000
Runs at the same time	2	4	10	50
Queue	standard	priority	priority	priority
Knowledge bases	2	3	10	100
Workspaces	2	3	10	400
MCP servers	2	5	20	100
Overage	no	yes	yes	yes

Image allowances are left out of this table on purpose: the published figures are being corrected. Read them from GET /api/v1/public/plans.

Each plan also states its reset, and it applies to tokens only: day when the plan has a daily token allowance (Free, Starter and Pro in the table above), otherwise month (Enterprise). Images and runs are counted per month on every plan.

A company can also carry quota overrides set for it on top of its plan. To see the limits that actually apply to you, read your own company rather than the price list (next section).

Where your company stands

These calls need a key with the billing:read scope. The default key scopes do not include it, so choose it when you create the key.

curl -s https://api.snaga.ai/api/v1/usage/quota \
  -H "Authorization: Bearer $SNAGA_API_KEY"

GET /api/v1/usage/quota is the one to read first. allowed says whether the company can run now (with a reason when it cannot); daily gives today's tokens with resets_at; counters lists every capped counter as {kind, used, limit, period, resets_at}; and resource_usage gives {count, limit, over_by} for agents, teams, knowledge bases and workspaces.

Call	Answers
`GET /api/v1/usage`	Tokens, runs, tool calls and cost for the current period. `?breakdown=model,source` splits it; `?agent_id=` gives one agent's usage.
`GET /api/v1/usage/timeseries`	A daily series of `runs`, `tokens` or `cost` over the last `days` (up to 90).
`GET /api/v1/usage/media`	Images and videos generated against the plan's media quotas.
`GET /api/v1/billing/plans`	The plans, with `current` marking yours and `checkout_available` saying whether you can upgrade to it.

total_cost is what your company is billed, in USD.

Set your own spend cap

A plan limits volume; a spend cap limits money. The cap is checked before every run starts.

curl -s -X PUT https://api.snaga.ai/api/v1/billing/budget \
  -H "Authorization: Bearer $SNAGA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"limit_usd": 50, "period": "monthly"}'

Field	Meaning
`limit_usd`	The cap, in USD. Required.
`period`	`monthly` (default), `weekly` or `daily`.
`soft_threshold`	Fraction of the cap that raises a soft alert. Default `0.8`.
`hard_threshold`	Fraction of the cap where runs stop. Default `1.0`.

The PUT replaces the whole setting: a field you leave out goes back to its default. GET /api/v1/billing/budget shows the cap and its live status, with soft_alert and hard_limit_reached; DELETE removes it. Changing it needs billing:write. The setup path in the web app asks for a monthly spend cap too.

Overage

On a paid plan you can let usage continue past the plan's token allowance and pay for the extra per million tokens. On 2026-10-19 the published rate was 0.42 USD per million input tokens and 1.68 USD per million output tokens (see overage in GET /api/v1/public/plans).

Overage needs a spend cap: PUT /api/v1/billing/overage with {"enabled": true} is refused on the free plan and when no cap is set. GET /api/v1/billing/overage shows the current state.

When a limit is reached

A refusal for a limit is a problem document whose code tells you what kind of limit it is. Read code, not the wording of detail.

`code`	What it means	What to do
`rate_limit_exceeded`	Too many requests too quickly.	Wait `Retry-After` seconds and retry.
`quota_exceeded`	A period allowance is used up.	Wait until `quota.resets_at`, or upgrade.
`run_quota_exceeded`	The run allowance is used up.	Wait for the reset, or upgrade.
`limit_reached`	A limit that does not reset on a clock, such as the number of agents.	Remove something, or change plan.

quota.kind (tokens, runs, tool_calls, images, videos) and quota.period (day, month) are always present on quota_exceeded and limit_reached, often with limit, used and remaining. A period wall answers 429 with Retry-After and an X-Quota-Resets-At header. A run stopped because the run allowance ran out carries error_code: run_quota_exceeded.

Key off code, never the status, for limit_reached. It answers 403 on POST /api/v1/runs, POST /api/v1/llm/* and POST /api/v1/tools/web_search, but 429 on POST /api/v1/sessions/{sessionId}/messages and POST /api/v1/agents/{agentId}/evaluations. The split is kept for older clients, not by design.

Every response also carries X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset, so a client can slow down before it is refused.

Changing plan

In the web app, open Settings → Plan and payment. From code, POST /api/v1/billing/checkout-session with a plan_id returns a url for payment, and POST /api/v1/billing/portal-session returns a url where invoices and payment methods are managed.

Governance and guardrails — per-agent and per-run cost caps.
Your first API call — creating a key with the scopes you need.