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 |
|---|---|
| Plan period | The current plan's part of this month: from the month's start, or from when the plan started if later |
| Usage charges | Priced usage during the plan period; only this counts against the plan's credit |
| Included credit used/remaining | The plan's monthly credit, prorated to the plan period, applied to that usage |
| Estimated bill | This month's invoice so far, across every plan the workspace was on: prorated fees, billed usage and prorated 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. Every plan is also warned when it has used 80% and 95% of its included credit, and when the credit runs out. Each alert fires once a month, is recorded for the workspace, and is emailed to its owners. Alerts are checked as usage is recorded (at most once a minute per workspace) and again daily.
After a plan change mid-month, usage from before the change never counts against the new plan's credit, and each plan's fee and credit are prorated by the days it was in force, exactly as the month's invoice is.
A plan may include a monthly quantity of some resources. That allowance is prorated the same way, covers the month's earliest usage of the resource first, and costs nothing: invoices show it as an included line at $0, and it never uses the included credit. Usage beyond it is billed as usual.
Invoices close on the 2nd of the following month. An invoice shows as being prepared until it is sent; one is held for review when some usage has no price yet, and goes out once it is priced. Prices only change going forward, so a price change never alters a past month. If a month was billed at a wrong price, the difference comes back as a credit note on that invoice: a refund if it was paid, or a lower amount due if not. Credits appear under the invoice's lines.
Budget alerts never stop work. Separately, on a plan that pauses when its included credit is exhausted (Starter), each paid step holds its estimated price before it runs and is refused with usage_limit_reached when it does not fit, so running work, even in parallel, never spends past the credit. Other plans continue, and usage beyond the credit is billed. 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.
Plan allowances and feature access
The public pricing page and pricing_get show monthly resource allowances and
feature access set by platform administrators. Allowances cover resource quantities
first; remaining charges use your plan's USD credit. Public pricing refreshes
within an hour, while execution checks use the current access rules.
Platform staff manage Admin → Plans → Edit access for assistant and authoring, pipelines, predictions, sandbox/plugin execution, and connected app tool calls. Use Set allowance for included resource quantities in billing units; allowance changes can start now or at a future time. Ordinary workspace administrators cannot change commercial plan entitlements.
All capabilities initially remain available on existing plans. If staff disable
a capability, its next execution returns 403 plan_feature_unavailable before
starting, including queued work and new calls in existing tool sessions. Existing
data remains readable. Contact an administrator or select a plan which includes
that capability; retrying unchanged will not restore access. A billing service
outage instead returns 503 billing_unavailable.
Choosing a plan during signup
Choose Starter or Pro on the pricing page, then create an account or sign in. Your choice stays with you through email confirmation. Choose an existing workspace or create one. Selecting Starter leaves any existing workspace subscription unchanged.
For Pro, the next page shows the plan's current monthly fee and usage credit. Workspace owners and admins can continue to Stripe to save a card. Pro activates when card setup is confirmed; the return page shows its status. Cancel checkout or choose Continue with current plan to keep using the workspace without upgrading. Enterprise plans continue through Contact sales.
Platform pricing links open the related landing deployment on Vercel. In local
development they open http://localhost:3100/pricing, including service pages.
NEXT_PUBLIC_LANDING_URL can override the fallback when no related URL resolves.
Platform admins manage Provider costs, Customer prices, and Included usage separately. Provider costs are internal supplier costs. Customer prices are what a plan charges per billing unit; explicit prices override provider cost plus plan margin. Included usage is a monthly resource allowance before charges.
Billing screens consistently call suppliers providers, including provider costs
and provider invoices. Older API fields named vendor retain their existing shape.