Usage models define how clients consume their purchased API access. Kobaru supports two models: pay-per-request and pay-per-time.
Overview#
When a client pays for API access, they receive a usage allocation. The usage model determines how that allocation is consumed:| Model | How it works | Best for |
|---|
| Pay-per-request | Each request decrements a counter | Variable usage patterns |
| Pay-per-time | Unlimited requests within a time window | High-frequency access |
Pay-per-request#
Clients purchase a bundle of requests. Each successful API call consumes one request from their balance.Configuration#
{
"extensions": {
"usage": {
"model": "pay_per_request",
"limit": 10,
"unit": "request"
}
}
}
How it works#
1.
Client pays and receives 10 requests
2.
Each request that reaches your backend decrements the counter (10 → 9 → 8...); some responses refund it (see Refunds) 3.
When counter reaches 0, access is denied
4.
Client must pay again for more requests
Tracking#
Usage is tracked atomically:One quota per payment, whatever its encoding, owned by the first route that uses it
Each request decrements it by one
Consistent across all edge locations
Refunds#
The use is consumed when the request reaches your backend. What happens next depends on your response:| Your response | Use | Payment settled? |
|---|
| 2xx | Consumed | Yes |
| 401, 403 | Refunded (upstream auth error) | No |
| 429 | Refunded (upstream rate limit) | No |
| 5xx | Refunded (server error) | No |
| Any other non-2xx (e.g. 400, 404, 422) | Consumed | No |
After a 2xx, if the settlement fails for good the use is refunded and the client gets 402; if the payment couldn't be claimed (503 claim_unavailable) or the gateway can't process its network right now (503 server_configuration_error, rpc_unavailable or bite_unavailable), it is refunded too. If the outcome is unknown (503 settlement_pending), the use stays consumed until the outcome is known (Kobaru resolves it on a retry or in the background); once it turns out settled, the next request with the same payment is served without costing another use.Example: Client has 8 requests remaining. Your API returns 500. Kobaru refunds the request, so they still have 8 remaining.
Pay-per-time#
Clients purchase unlimited access for a specified duration. The clock starts on first use.Configuration#
{
"extensions": {
"usage": {
"model": "pay_per_time",
"limit": 3600,
"unit": "second"
}
}
}
How it works#
1.
Client pays and receives a 1-hour access window
2.
Timer starts on the first request
3.
Unlimited requests allowed until timer expires
4.
After expiration, access is denied
Tracking#
Activation is tracked per payment:Owned by the first route that uses it
Stores the activation time
Expires automatically after the time limit
No refunds#
Time-based access is not refundable. Once the timer starts, the time elapses regardless of usage or errors. The payment is settled on the first 2xx response.
Choosing a usage model#
Use pay-per-request when:#
Usage varies significantly between clients
You want to charge proportionally to consumption
Clients make occasional, valuable requests
You want to offer refunds for errors
Use pay-per-time when:#
Clients need high-frequency access
Usage is predictable and consistent
You want to reduce payment friction
Simplicity is more important than precise billing
Configuration examples#
Per-request bundle#
Sell 100 requests for $0.10:Time-based access#
Sell 1 hour of unlimited access for $1.00:
Usage in the proxy#
When using the transparent proxy, configure usage models in the Kobaru Console:3.
Set Usage model to pay_per_request or pay_per_time
4.
Set Limit (requests or seconds)
Security - How usage tracking prevents abuse Modified at 2026-10-30 21:41:30