Usage & budget
Two read endpoints cover accounting: /v1/usage aggregates your API activity and its cost; /v1/usage/budget reports the account budget pool so you can self-check before running work that would be refused.
Both accept either a bearer key or a signed-in dashboard session (details), and both count against the reads bucket (60/min).
One pool. Scans and exports run over the API deplete the same budget the regsn.app UI consumes — there is no separate API meter. All *_cents values are US cents.
Usage
GET /v1/usage
| Query parameter | Default | Notes |
|---|---|---|
from | 30 days ago | ISO 8601 date-time. |
to | now | ISO 8601 date-time. Must not be earlier than from (422 otherwise). |
group_by | day | day, endpoint, or key. Unrecognised values fall back to day. |
curl "https://api.regsn.app/v1/usage?group_by=endpoint&from=2026-07-01T00:00:00Z" \
-H "Authorization: Bearer $REGSN_API_KEY"200:
{
"totals": {
"request_count": 412,
"scan_count": 9,
"export_count": 31,
"error_count": 3,
"total_cost_cents": 618,
"avg_latency_ms": 184
},
"buckets": [
{
"key": "POST /scans",
"request_count": 9,
"scan_count": 9,
"export_count": 0,
"error_count": 1,
"cost_cents": 512,
"avg_latency_ms": 2210
}
],
"filters": {
"from": "2026-07-01T00:00:00.000Z",
"to": "2026-07-20T12:00:00.000Z",
"group_by": "endpoint"
}
}Semantics
| Field | Meaning |
|---|---|
totals | Aggregates over the whole window. error_count counts responses with status ≥ 400. avg_latency_ms is null when no latency data exists. |
buckets[].key | Depends on group_by: a YYYY-MM-DD day, a METHOD /path pair, or an API-key id. |
buckets[].cost_cents | Cost attributed to requests in the bucket — a scan’s cost lands on the request that created it, an export’s on the request that queued it. Reads cost nothing. |
With group_by=key, each bucket is additionally decorated so you can attribute usage without a second lookup:
{
"key": "3f2c…",
"key_name": "production-backend",
"key_prefix": "regsn_live_aBcD…",
"key_revoked": false,
"request_count": 388
}Revoked keys are included — history keeps its attribution. Day buckets sort chronologically; endpoint and key buckets sort by cost, highest first.
Errors
Status · code | When |
|---|---|
422 validation_error | from/to not parseable as ISO 8601, or from after to (field code invalid_range). |
Budget
GET /v1/usage/budget — the same accounting that decides whether POST /v1/scans returns 402. Call it before a batch run to avoid burning a scan-bucket slot on a request that will be refused.
curl https://api.regsn.app/v1/usage/budget \
-H "Authorization: Bearer $REGSN_API_KEY"200:
{
"allowed": true,
"budget_cents": 5000,
"spent_cents": 3182,
"remaining_cents": 1818,
"role": "user",
"message": "$18.18 remaining of $50.00"
}| Field | Meaning |
|---|---|
allowed | Whether a new scan would currently be accepted on budget grounds. |
budget_cents | The account’s budget cap. null means no cap. |
spent_cents | Spend against the pool. |
remaining_cents | budget_cents − spent_cents, floored at 0 when exhausted; null when uncapped. |
role | user or admin. |
message | Human-readable summary of the same numbers. |
When the pool is exhausted, allowed is false and the next POST /v1/scans returns 402 budget_exhausted. Budgets are set at account level by your workspace administrator — raising a cap is a conversation with them, not an API call or a self-service setting.
See also
- Rate limits — request-frequency limits, distinct from budget.
- Scans — estimate a scan’s cost before running it.
- Authentication — key attribution and the dual-auth rule.