Usage and billing
Inspect metering and distinguish consumer billing from provider callbacks
Usage endpoints expose workspace metering to org:manage callers. GET /usage accepts from/to ISO dates; the range is inclusive, defaults to the last 30 UTC days and is limited to 366 days. Currency amounts are decimal strings; retain precision when calculating totals.
GET /usage/billing reads the current billing month. GET /usage/rates reads workspace rates. GET /usage/operations lists metered operations with offset paging and optional parent operation ID; GET an operation's charges to inspect its cost details. GET /query-executions lists query activity with offset and optional execution ID.
curl --fail-with-body --get -H "Authorization: Bearer $SEMOGRAM_API_KEY" \
--data-urlencode 'from=2026-10-01' --data-urlencode 'to=2026-10-05' \
'https://platform.semogram.com/api/v1/usage'Alerts and limits
GET/PUT /usage/alerts manages monthlyBudget and threshold settings. Budgets/alerts are not a hard spending stop; plan or credit enforcement is a separate mechanism that can reject work. GET /pricing is public and describes available pricing.
Billing navigation
POST checkout and portal routes require org:manage and accept a same-origin returnPath. They return a URL for the authorized user to continue the billing flow. GET invoices reads billing records. POST downgrade changes the workspace plan and should be treated as an intentional administration action, not a read or a health check. Billing routes can return unavailable when Stripe is not configured.
Provider webhook
POST /billing/stripe-webhook is a Stripe callback, verified against the raw request body and Stripe-Signature with the configured webhook secret. It does not use a consumer Bearer key. Do not call it to change a subscription or imitate a billing event; use checkout/portal and the provider's configured callback delivery.