---
title: "Get Billing"
method: GET
path: "/v1/account/billing"
tags: ["Account"]
---

# Get Billing

`GET /v1/account/billing`

## Request

- Base URL: `https://api.ensemble.markets` (the document declares no server; this is the origin it was published from)
- URL: `https://api.ensemble.markets/v1/account/billing`
- Auth: HTTP bearer

Headroom for metered work: what the account can still spend, what is
held by builds and runs in flight, and what one run or build holds.

Every build and run is metered in cents. The figures here are the ones
admission uses, so `remaining_cents` below `projected_run_cents` means
the next run is refused with 402. A 402 is final for this request; no work
starts. `usage_help_url` explains the
account limitation. Projected holds are estimates, not final charges.
This read may initialize the account's billing record and signup grant.

## Response `200`

Successful Response

- AccountBilling: What the account can spend right now, in the same figures the 402 uses. Every build and run is metered in units of one cent. Admission holds the projected cost against `remaining_cents`; the request that would take it below zero is refused with 402 `insufficient_credits` (no funding on record) or `insufficient_funds` (spending cap reached for the period).
  - `plan` string, required: Billing plan: starter | hobby | business
  - `phase` 'credits' | 'metered' | 'unfunded' | 'unavailable', required: credits: local credits cover new work, previously accrued metered usage remains owed; metered: credits are spent, usage bills against the spending cap; unfunded: credits are spent and there is no active subscription (every metered request is refused); unavailable: the decision needs Stripe and Stripe could not be reached.
  - `remaining_cents` integer, required: Headroom for new work: credits plus verified metered headroom (cap minus accrued usage), minus outstanding holds. Unverified metered funds are excluded. A request is refused when its projected cost exceeds this.
  - `held_cents` integer, required: Projected cost of builds and runs currently in flight
  - `credits_remaining_cents` integer, required: Local credits left: monthly included, signup grant and promo
  - `spending_cap_cents` integer, required: Metered spend allowed per billing period (dashboard setting)
  - `period_usage_cents` integer, nullable: Metered liability incurred this billing period, including queued Stripe delivery. Adding credits never reduces this amount. Null when the billing period could not be verified.
  - `projected_run_cents` integer, required: What one run of a stored script holds at admission
  - `projected_build_cents` integer, required: What one build or rebuild on the default agent tier holds at admission
  - `has_payment_method` boolean, required: A Stripe customer exists for the account
  - `has_subscription` boolean, nullable: Active subscription: true or false when verified, null when unavailable
  - `current_period_start` string, date-time, nullable
  - `current_period_end` string, date-time, nullable
  - `signup_credits_expire_at` string, date-time, nullable: When the unspent signup grant lapses
  - `usage_help_url` string, required: Informational help for usage, holds and account limitations
  - `dashboard_url` string, required: Deprecated alias of usage_help_url (informational help)

## Other responses

- `4XX`: The request was refused; `error.type` says why
- `5XX`: The server failed; quote `X-Request-Id` when reporting it

---

[API](https://skmtc.dev/ensemble/apis/ensemble-api.md) · [All operations](https://skmtc.dev/ensemble/apis/ensemble-api/llms.txt) · [OpenAPI document](https://skmtc.dev/ensemble/apis/ensemble-api/revisions/4c0fbd80c197?raw)