Usage, budgets and audit
Read the usage ledger and reports, understand budgets and rate limits, and read the audit trail.
The usage ledger
Every model call is one ledger row, with the workspace, project, client, agent, model class, deployment, credential, input, output, cached and reasoning tokens, and estimated cost. Money is always a decimal string in US dollars, never a floating-point number.
curl "$SPARQ_API_URL/v1/admin/usage?project_id=$PROJECT_ID" -H "Authorization: Bearer $SPARQ_KEY"This list returns 50 rows per page, newest first, and accepts project_id, credential_id, since
and cursor.
Usage reports
Group usage by up to three dimensions: audience_tenant, agent, model_class, project,
credential or day. Without since and until, the report covers the last 30 days.
curl "$SPARQ_API_URL/v1/admin/usage/report?group_by=audience_tenant&group_by=day" \
-H "Authorization: Bearer $SPARQ_KEY"A client admin sees only their own client's usage.
Budgets
Budgets are reserved before each model call, from the run up through the session, user, client,
project and workspace, plus a cap per credential. A soft limit alerts and may downgrade the model
class; a hard limit stops the call before it is sent. Delegation to another agent cannot multiply
spend. Project budgets are set on the project (budgets).
Rate limits
Requests and tokens are limited per credential and per client. Over the limit, calls are refused with
429 rate_limited. If the limiter itself cannot be reached, calls are refused rather than allowed.
Audit
Audit records are append-only, chained by hash per workspace, and written in the same transaction as the action they record: if the audit write fails, the action is undone. Every authorization decision is recorded with its policy version, including refusals.
curl "$SPARQ_API_URL/v1/admin/audit?project_id=$PROJECT_ID" -H "Authorization: Bearer $SPARQ_KEY"This list returns 100 records per page, oldest first.