Billing API
Read an organization's bill estimate, its monthly billing statements, and the plan catalogue.
GET /v1/accounts/{account_id}/billing/summaryReturns the organization's compute-unit (CU) usage for a period, each step of the bill calculation, and the resulting amount in USD. The path uses accounts because organizations used to be called accounts; use the organization's ID.
Permission: view_billing on the organization. Organization Owners, Admins and Billing admins have it; Writers, Members and Partners don't.
| Query parameter | Default | Description |
|---|---|---|
since_seconds | 2592000 (30 days) | Look-back window ending now. Minimum 3600 (1 hour), maximum 34560000 (400 days) |
curl -s -H "Authorization: Bearer $TOKEN" \
"https://platform.groundfloor.cloud/v1/accounts/$ORGANIZATION_ID/billing/summary?since_seconds=604800" | jq .The summary is an estimate, not an invoice. While status is estimate, the per-CU price is a placeholder (pricing_final is false) and storage and network usage are reported as 0. Don't present these amounts to your own customers as a final bill.
Response
| Field | Description |
|---|---|
account_id | The organization ID |
period_start, period_end | The window the figures cover |
billing_tier | low, mid, high, or strategic. Sets the multiplier applied to usage |
status | estimate or final. Expect estimate until billing is generally available |
is_estimate | true while status is estimate |
pricing_final | false while the per-CU rates and tier multipliers aren't locked |
ai_usage_only | true when compute, storage and network are all 0, so the figures cover AI usage only |
ai_usage_truncated | true when the look-back window is longer than a day. AI usage is read from a capped request log, so for longer windows the AI figure can be understated |
breakdown | CU by source: compute, storage, network, ai |
raw_cu | Sum of the breakdown, before the multiplier |
multiplier | The billing_tier multiplier |
adjusted_cu | raw_cu times multiplier |
sell_price_per_cu_usd | Price of one CU |
base_bill_usd | adjusted_cu times the price |
discount | Fractional discount applied, from 0 up to but not including 1 |
final_bill_usd | base_bill_usd after the discount |
note | A caveat in plain text. While status is estimate it begins with "ESTIMATE — NOT A FINAL BILL." |
What the sources currently measure:
- Compute: Coderunner run time for functions, jobs and schedules, and allocated CPU and memory over deployed time for services. It's based on deployment records, not a live measurement.
- Storage and network: not metered yet; always
0. - AI: not available yet; always
0. The LLM gateway is coming soon; once it is, token usage through it is planned to be converted to CU.
Responses can be cached for a few minutes, so the AI figure may lag slightly behind recent requests.
Billing statements
GET /v1/accounts/{account_id}/billing-statements
GET /v1/accounts/{account_id}/billing-statements/{statement_id}
GET /v1/accounts/{account_id}/billing-statements/{statement_id}/export.csvYour organization's monthly statements, newest period first. Only statements Groundfloor has issued, or later voided, are returned. Permission: view_billing on the organization.
The list takes status (issued or void), limit (1 to 200, default 50) and offset, and returns items and total_count. Amounts are decimal strings in currency (USD).
| Field | Description |
|---|---|
period_start, period_end | The month covered. period_end is exclusive |
plan_tier | The plan the statement was priced on |
status | issued or void, with issued_at and voided_at |
base_fee_usd, usage_subtotal_usd, included_credit_usd, total_usd | The plan's base fee, the usage charges, the usage included in the plan, and the total |
contains_estimates | true when some usage is estimated; those lines have estimated: true |
warnings | Codes for anything unusual about the statement |
lines | Detail only. One line per workspace resource and meter: workspace_name, resource_label, meter, billable_quantity, billable_unit, unit_price_usd, amount_usd and more |
export.csv returns the lines plus a summary as a CSV file. An unknown statement, or one that belongs to another organization, is 404.
Plan catalogue
GET /v1/billing/plansThe plans and unit rates. Any signed-in user can read it. Each plan has a key (free, indie, business or enterprise), a label, its monthly_fee_usd and included_usd (null for Enterprise, which is agreed per organization), and its limits; rates holds the unit prices. Only the workspaces and file_storage_bytes limits are enforced today; the others are listed for information. See Quotas and limits.
Errors
| Status | Meaning |
|---|---|
| 403 | Missing view_billing on the organization |
| 404 | Organization not found |
| 422 | since_seconds outside the allowed range |