Usage models#
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 successful request decrements the counter (10 → 9 → 8...)
3.
When counter reaches 0, access is denied
4.
Client must pay again for more requests
Tracking#
Usage is tracked atomically in Redis:Key: usage:{paymentHash}:remaining
Operation: DECR on each request
Thread-safe across all edge locations
Refunds#
If your backend returns an error, Kobaru automatically refunds the request:| Status code | Refunded? | Reason |
|---|
| 200-299 | No | Successful response |
| 400, 404, 422 | No | Client error |
| 401, 403 | Yes | Upstream auth error |
| 429 | Yes | Upstream rate limit |
| 500-599 | Yes | Server error |
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 in Redis:Key: usage:{paymentHash}:activated
Value: Activation timestamp
TTL: Automatically expires after the time limit
No refunds#
Time-based access is not refundable. Once the timer starts, the time elapses regardless of usage or errors.
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-01-04 13:59:25
