Usage and billing
View as Markdown# Usage and billing
> The one billable unit — the AI conversation — how it is metered, how model weights apply, plans and quotas, and the usage API.
K-Agent bills one unit everywhere: the **AI conversation**. The dashboard, the API and the pricing page all use the same definition.
## The unit: AI conversation
> **Definition:** one end user (or one session when anonymous) with one agent, in a fixed 24-hour window starting at the agent's first reply, up to 50 agent replies. Reply 51, or any reply after 24 h, opens a new conversation.
- A **reply** is a run that ends with the outcome `answered`. Runs that end `handed_off`, `failed`, `cancelled` or `superseded` are never billed, never count as replies and never open a window.
- The window is per **end user**, not per session: a verified customer who opens three sessions with the same agent in one day uses one window. Without an end user, the session is the subject.
- A window also closes after **300,000 input tokens**; the next reply opens a new one.
- Human conversations are never billed. Handoffs and your team's replies cost nothing, and seats are not the meter.
## The meter
| Event | Units |
|---|---|
| First agent reply in a window | 0.25 × w |
| Second reply | + 0.75 × w (the window now totals 1.0 × w) |
| Replies 3–50 | 0 |
| One-shot `ask` | 0.25 × w × the number of started 50,000-token blocks of input (at least 1) |
| Runs that hand off, fail, are cancelled or are superseded | 0 |
| Runs that fail at the provider | 0 (the provider cost is still recorded) |
| The dashboard's test panel | 0 (the provider cost is still recorded) |
**w** is the model weight. It is fixed when the window opens: the weight of the model that produced the first reply. One-shot input counts every model call of the run, cached tokens included. Stateless calls to the OpenAI-compatible endpoint are billed like `ask`.
### Model weights
| Tier | Models | Weight |
|---|---|---|
| Standard | deepseek-flash, gpt-6-luna, Gemini 3.5 Flash-Lite | 1× |
| Advanced | Gemini 3.8 Flash, Claude Haiku 4.5, deepseek-v4-pro | 3× |
| Premium | Claude Sonnet 5.5 | 6× |
| Your own key (BYOK) | Any model, billed by your provider | 0.2× (platform fee only) |
The table is published and reviewed every quarter. `GET /v1/models` returns each model's tier, weight and whether your plan allows it.
### Worked examples
| What happened | Units |
|---|---|
| A customer asks one question on a Standard model | 0.25 |
| The same customer sends 8 messages that day | 1.0 |
| They come back 30 hours after the first reply and ask again | 1.0 + 0.25 |
| 60 replies within 24 hours | 1.0 (replies 1–50) + 1.0 (replies 51–52 open a new window; 53–60 are free) = 2.0 |
| A three-reply conversation on Claude Haiku 4.5 (Advanced) | 1.0 × 3 = 3.0 |
| A three-reply conversation on your own OpenAI key | 1.0 × 0.2 = 0.2 |
| A one-shot ask with 120,000 input tokens on a Standard model | 0.25 × 3 = 0.75 |
| The agent hands the first question to your team | 0 |
## Plans
Prices in Saudi riyals, excluding VAT.
| Plan | Price / month | Included AI conversations (Standard models) | Overage | Seats |
|---|---|---|---|---|
| Free | 0 | 100 (hard cap) | — | 2 |
| Starter | 299 | 500 | SAR 1.00, invoiced monthly | 5 |
| Business | 899 | 2,000 | SAR 1.00, invoiced monthly | 15 |
| Scale | 2,499 | 7,500 | SAR 1.00, invoiced monthly | 40 |
| Enterprise | Custom | Custom | Custom | Custom |
Advanced counts 3, Premium 6, your own key 0.2 per conversation.
- **Models per plan:** Free includes Standard models and your own keys; Starter adds Advanced; Business and above include every model.
- **Plan changes** are made by the Kerneltics team in v1 — contact us to upgrade. Online payment and ZATCA e-invoicing arrive in v1.1.
## Quotas
- The quota is **per organization**, per calendar month in Asia/Riyadh time.
- It is checked when a window **opens**. A window that is already open always finishes.
- **Free stops at 100 units.** Sessions then reply with a short notice and hand the conversation to your team — customers never see a billing error — and one-shot calls return `429 quota_exceeded` with `x-should-retry: false`.
- **Paid plans never stop** in v1. Units beyond the included amount are reported as `overage_units` and invoiced monthly. A contract can set a hard cap instead.
- Alerts fire at **75% and 100%**: a banner in the dashboard and the `usage.threshold_reached` webhook with `{percent}`.
- If the meter itself has a problem, it fails open: your agent keeps answering.
### Daily cost caps
To protect you from runaway spend, each organization also has a daily cap on model cost (Free $1, Starter $10, Business $30, Scale $100 by default; adjustable on request). Past the cap, sessions hand off with a notice and `ask` returns `429 cost_cap_exceeded` until the next day.
Test-panel runs on platform models are limited to 200 per project per day (`429 playground_limit_reached`); with your own provider key they are unlimited.
## Usage API
```bash
curl https://api.k-agent.kerneltics.com/v1/usage/summary \
-H "Authorization: Bearer $KAGENT_API_KEY"
```
```json
{
"object": "usage_summary",
"plan": "starter",
"period": { "start": 1790802000, "end": 1793480400, "timezone": "Asia/Riyadh" },
"included": 500,
"used": 212.5,
"remaining": 287.5,
"overage_units": 0,
"hard_cap": false
}
```
`GET /v1/usage?group_by=day|agent|model|channel&from=…&to=…` breaks units, tokens and cost down over time. Both need the `usage:read` scope. Every run also reports its own `usage.units` and `usage.weight`.
K-Agent bills one unit everywhere: the AI conversation. The dashboard, the API and the pricing page all use the same definition.
The unit: AI conversation
Section titled “The unit: AI conversation”Definition: one end user (or one session when anonymous) with one agent, in a fixed 24-hour window starting at the agent’s first reply, up to 50 agent replies. Reply 51, or any reply after 24 h, opens a new conversation.
- A reply is a run that ends with the outcome
answered. Runs that endhanded_off,failed,cancelledorsupersededare never billed, never count as replies and never open a window. - The window is per end user, not per session: a verified customer who opens three sessions with the same agent in one day uses one window. Without an end user, the session is the subject.
- A window also closes after 300,000 input tokens; the next reply opens a new one.
- Human conversations are never billed. Handoffs and your team’s replies cost nothing, and seats are not the meter.
The meter
Section titled “The meter”| Event | Units |
|---|---|
| First agent reply in a window | 0.25 × w |
| Second reply | + 0.75 × w (the window now totals 1.0 × w) |
| Replies 3–50 | 0 |
One-shot ask |
0.25 × w × the number of started 50,000-token blocks of input (at least 1) |
| Runs that hand off, fail, are cancelled or are superseded | 0 |
| Runs that fail at the provider | 0 (the provider cost is still recorded) |
| The dashboard’s test panel | 0 (the provider cost is still recorded) |
w is the model weight. It is fixed when the window opens: the weight of the model that produced the first reply. One-shot input counts every model call of the run, cached tokens included. Stateless calls to the OpenAI-compatible endpoint are billed like ask.
Model weights
Section titled “Model weights”| Tier | Models | Weight |
|---|---|---|
| Standard | deepseek-flash, gpt-6-luna, Gemini 3.5 Flash-Lite | 1× |
| Advanced | Gemini 3.8 Flash, Claude Haiku 4.5, deepseek-v4-pro | 3× |
| Premium | Claude Sonnet 5.5 | 6× |
| Your own key (BYOK) | Any model, billed by your provider | 0.2× (platform fee only) |
The table is published and reviewed every quarter. GET /v1/models returns each model’s tier, weight and whether your plan allows it.
Worked examples
Section titled “Worked examples”| What happened | Units |
|---|---|
| A customer asks one question on a Standard model | 0.25 |
| The same customer sends 8 messages that day | 1.0 |
| They come back 30 hours after the first reply and ask again | 1.0 + 0.25 |
| 60 replies within 24 hours | 1.0 (replies 1–50) + 1.0 (replies 51–52 open a new window; 53–60 are free) = 2.0 |
| A three-reply conversation on Claude Haiku 4.5 (Advanced) | 1.0 × 3 = 3.0 |
| A three-reply conversation on your own OpenAI key | 1.0 × 0.2 = 0.2 |
| A one-shot ask with 120,000 input tokens on a Standard model | 0.25 × 3 = 0.75 |
| The agent hands the first question to your team | 0 |
Prices in Saudi riyals, excluding VAT.
| Plan | Price / month | Included AI conversations (Standard models) | Overage | Seats |
|---|---|---|---|---|
| Free | 0 | 100 (hard cap) | — | 2 |
| Starter | 299 | 500 | SAR 1.00, invoiced monthly | 5 |
| Business | 899 | 2,000 | SAR 1.00, invoiced monthly | 15 |
| Scale | 2,499 | 7,500 | SAR 1.00, invoiced monthly | 40 |
| Enterprise | Custom | Custom | Custom | Custom |
Advanced counts 3, Premium 6, your own key 0.2 per conversation.
- Models per plan: Free includes Standard models and your own keys; Starter adds Advanced; Business and above include every model.
- Plan changes are made by the Kerneltics team in v1 — contact us to upgrade. Online payment and ZATCA e-invoicing arrive in v1.1.
Quotas
Section titled “Quotas”- The quota is per organization, per calendar month in Asia/Riyadh time.
- It is checked when a window opens. A window that is already open always finishes.
- Free stops at 100 units. Sessions then reply with a short notice and hand the conversation to your team — customers never see a billing error — and one-shot calls return
429 quota_exceededwithx-should-retry: false. - Paid plans never stop in v1. Units beyond the included amount are reported as
overage_unitsand invoiced monthly. A contract can set a hard cap instead. - Alerts fire at 75% and 100%: a banner in the dashboard and the
usage.threshold_reachedwebhook with{percent}. - If the meter itself has a problem, it fails open: your agent keeps answering.
Daily cost caps
Section titled “Daily cost caps”To protect you from runaway spend, each organization also has a daily cap on model cost (Free $1, Starter $10, Business $30, Scale $100 by default; adjustable on request). Past the cap, sessions hand off with a notice and ask returns 429 cost_cap_exceeded until the next day.
Test-panel runs on platform models are limited to 200 per project per day (429 playground_limit_reached); with your own provider key they are unlimited.
Usage API
Section titled “Usage API”curl https://api.k-agent.kerneltics.com/v1/usage/summary \ -H "Authorization: Bearer $KAGENT_API_KEY"{ "object": "usage_summary", "plan": "starter", "period": { "start": 1790802000, "end": 1793480400, "timezone": "Asia/Riyadh" }, "included": 500, "used": 212.5, "remaining": 287.5, "overage_units": 0, "hard_cap": false}GET /v1/usage?group_by=day|agent|model|channel&from=…&to=… breaks units, tokens and cost down over time. Both need the usage:read scope. Every run also reports its own usage.units and usage.weight.