Usage API
The usage service accepts usage reports (for non-proxied services), progress updates, and completion callbacks for async jobs. All requests use HMAC-signed headers (body + timestamp, signed with service secret).
Base URL and path
Base URL is configurable. Default path prefix /api/usage; under ECS /usage/api/v1. All endpoints below are relative to that prefix.
Report usage
POST /report
Body: { userId, serviceId, unitsUsed, timestamp }. Headers: X-Tollara-Signature, X-Tollara-Timestamp (signature = HMAC(body + timestamp, serviceSecret)). Use for non-proxied services that report usage themselves. For pre-flight before accepting work (credits, caps), use core usage estimate (POST /billing/usage/estimate or POST /service-keys/estimate-usage); see Proxied vs non-proxied.
If your backend reports usage, keep your own request logs for reconciliation. Include the tollara.ai request id when available, your internal request id, subscriber or service key reference, endpoint, timestamp, status, units reported, and the tollara.ai usage response. Keep these logs for at least 24 months after the usage date, and longer while a refund, chargeback, audit, fraud review, tax inquiry, or legal dispute is open.
Progress (async)
POST /progress/{requestId} (or use the full progressUrl from the async response).
Body: { stage, percentageComplete, errorMessage?, timestamp }. Same signing as report.
Completion (async)
POST /complete/{requestId} (or use the full callbackUrl from the async response).
Body: { status, result?, resultUrl?, contentType?, units?, timestamp }. Same signing.
Recommended policy: use resultUrl for large outputs, and keep inline result to a short summary/error text. Inline result storage is capped server-side.
If your result is HTML, treat it as untrusted content on the client and render via link-out or sanitized viewer, not raw embedding.
The SDK provides reportUsage, reportProgress, and reportCompletion. See SDK overview.
