Credits & limits
A practical reference to how the cloro API meters usage: what a request costs in credits, how rate and concurrency ceilings are enforced, and which response headers let you watch consumption in real time.
Overview
Every call to the cloro API is metered through a credit balance and two independent throttles: a per-second request rate and a cap on how many requests may run at the same time. Credits are drawn from your account balance only when a request finishes successfully. Requests that fail with a client error in the 4xx range are never billed, so retries after a validation mistake will not erode your balance.
Synchronous monitor calls under /v1/monitor/* are priced at a flat rate of 7 credits per successful request. The cost does not vary with the number of pages returned or the features toggled on the request. For batch submissions, billing is tracked at the level of each individual task rather than the batch as a whole, and every task result carries its own creditsToCharge and creditsCharged fields so you can reconcile spend task by task.
Response headers
The headers attached to a response depend on the endpoint family. Rate-limit headers accompany every endpoint under /v1/*. Monitor endpoints under /v1/monitor/* additionally return credit and concurrency headers.
Rate limit (all endpoints)
| Field | Type | Description |
|---|---|---|
| X-RateLimit-Limit | integer | Maximum requests permitted within a single one-second window. The ceiling is 500. |
| X-RateLimit-Remaining | integer | Requests still available before the current one-second window resets. |
Credits (monitor endpoints)
| Field | Type | Description |
|---|---|---|
| X-Credits-Remaining | integer | Credit balance left on the account after this request settled. |
| X-Credits-Charged | integer | Credits deducted for this specific request. |
Concurrency (monitor endpoints)
| Field | Type | Description |
|---|---|---|
| X-Concurrent-Limit | integer | Ceiling on requests that may be in flight at once for this account. |
| X-Concurrent-Current | integer | Number of requests currently running, including this one. |
| X-Concurrent-Remaining | integer | Free concurrent slots still available. |
Concurrency limits
The concurrency cap governs how many requests a single API key may process in parallel. It is applied per key and per account, and it exists to keep throughput predictable for everyone on the platform. When a new request would push you past the ceiling, the API rejects it with a 429 Too Many Requests response rather than queuing it silently.
Reading the concurrency headers across two overlapping requests shows the counter advancing: with a limit of 10, the first in-flight request reports a current count of 1 and 9 remaining, while a second concurrent request reports a current count of 2 and 8 remaining.
Response example
A rejected request returns a structured error you can branch on programmatically:
{
"error": {
"code": "CONCURRENT_LIMIT_EXCEEDED",
"message": "The account has reached its maximum number of simultaneous requests.",
"details": {
"limit": 10,
"current": 10
},
"timestamp": "2026-08-14T09:32:11.482Z"
}
}A successful monitor task result includes the per-task credit fields used for batch reconciliation:
{
"taskId": "tsk_7Qm2xLf9",
"status": "completed",
"creditsToCharge": 7,
"creditsCharged": 7
}Notes
Treat a 429 as a signal to back off, not to fail. Retrying with exponential backoff, doubling the wait after each attempt, lets transient contention clear on its own. Watch X-Concurrent-Remaining and X-RateLimit-Remaining to throttle before you hit either ceiling, and alert on X-Credits-Remaining so a low balance never interrupts production traffic. For unexpected charges, review your request logs to confirm which features were enabled, and reach out to [email protected] with the relevant request IDs for billing questions.