Usage and budgets
Inspect charges, included credit, operation costs and advisory budget alerts
Workspace usage shows what operations are charged across projects and shared resources. Reports include quantities in billing units, applicable unit prices and amounts. The plan view separates usage charges, included credit, remaining credit and estimated bill.
You need a Semogram account as owner/admin, or an org:manage API key, to read workspace-specific usage and manage budgets. Use the workspace's current rate card/plan rather than copying prices from a static example.
Understand the report
| Signal | Meaning |
|---|---|
| Usage charges | Metered activity's priced amount |
| Included credit used/remaining | Plan credit applied to usage |
| Estimated bill | Current plan fee and applicable usage beyond credit |
| Category/project/day totals | Ways to inspect the selected UTC period |
| Operation charges | One operation and its descendants' line items |
| Unrated quantity | Usage not priced yet; not evidence of free work |
Default usage history is the last 30 UTC dates. from/to dates are inclusive, must be ordered and can span at most 366 days. Month-to-date billing is a separate calendar-month view. Amounts are USD decimal strings in API/MCP responses; preserve precision.
Example: a monthly alert budget
Open Settings → Usage. Inspect Plan, Charges, breakdowns, operations and current Prices. In Budget and alerts set Monthly budget (USD) to 250.00 and save. Read back the budget and recorded threshold alerts. Leaving it empty clears budget alerts.
Read this workspace's current plan, month-to-date bill, rate card and recent usage. Identify which projects and operations contribute most, distinguishing usage charges from included credit and the estimated bill. Prepare a USD 250 monthly alert-budget proposal; do not call it a hard spending cap.MCP exposes usage reads, not budget mutation. Apply the reviewed budget via UI/API.
curl --request PUT "https://platform.semogram.com/api/v1/usage/alerts" \
--header "Authorization: Bearer ${SEMOGRAM_ADMIN_KEY}" \
--header "Content-Type: application/json" \
--data '{"monthlyBudget":"250.00","thresholds":[50,80,100]}'GET the same route to inspect the budget/alerts. Read /api/v1/usage, /usage/billing, /usage/rates, /usage/operations and /usage/operations/<OPERATION_UUID>/charges for the corresponding reports under the same /api/v1 prefix. These require org:manage.
Use organization_usage_get (optional from/to), usage_billing_get, usage_rate_card_get, operation_list and operation_charges_get. Read next cursors/offsets when listing. Workspace-specific operations require org:manage. pricing_get reads public prices and is distinct from this workspace's rate card.
Alerts are not a hard cap
Budget thresholds default to 50%, 80% and 100% of estimated monthly bill. The authorized alert evaluator records crossed thresholds, once per threshold/month, and included-credit exhaustion. Inspect the recorded alerts; this does not promise email/Slack delivery or immediate evaluation on every request.
Budget alerts never stop work. Separately, a plan configured to pause when included credit is exhausted can stop new paid work and return usage_limit_reached. Other plans may continue with additional billed usage. Inspect the actual plan behavior before relying on a budget to constrain spending.
Per-prediction runtime/token/external-call budgets are separate execution controls. They do not replace workspace usage accounting, and unavailable cost estimates are not zero cost.