Semogram Docs
APIResources

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. Each plan includes featureAccess (assistant, pipelines, predictions, sandboxes, integrations) and allowances, an array of { meterKey, quantity } entries. Quantities are decimal strings in billing units per month. Only currently active allowances appear. This endpoint and pricing_get share the same contract and can be cached for an hour; neither authorizes execution.

Platform staff control feature access in Admin → Plans → Edit access. Disabled features return 403 plan_feature_unavailable before execution, including queued work and new remote tool calls. Unreadable access rules return 503 billing_unavailable. Existing data stays readable.

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

Repeating a downgrade after the workspace has moved to Starter returns 409 already_free.

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.

Customer prices use an explicit admin plan price first, then provider cost plus plan margin. Explicit prices appear even without a provider-cost record. A resource without either source has no price entry, rather than a zero price.