---
title: "read_balance"
description: "Generated reference for the management action read_balance: its description, access metadata, payload contract, and registration status."
slug: /reference/actions/read-balance
order: 3
visibility: public
redirects_from: []
---

# read\_balance

Generated automatically from the [published contract sources](/cloud/reference/about/#contract-sources).

A script calls this action over HTTPS at `POST https://turnzero.ai/api/v1/read_balance`, with a bearer credential and the action's payload as the JSON body. It also accepts `GET`. An MCP connection lists this action as the tool `read_balance`.

OAuth access tokens and minted tokens, including the turnzero command's computer token, are bearer credentials. The action determines which kinds, scopes and grants it accepts ([Sign-in, sessions, and tokens](/cloud/concepts/sign-in-sessions-and-tokens/)).

**Build metadata:** Registered in this build. Registration describes the default dispatcher in this build. It does not guarantee that a caller has the required credential or grant, that a tool is listed for that connection, or that the required service is configured.

## Contract description

Read your account's balance, warnings and pause state for this UTC month, with usage lines by application, rate key and environment\. Awake time, stored data and transfer through the egress gateway or from storage areas post at the daily pass for the previous UTC day\. Monthly items already held at the start of a UTC month post at that month's first daily pass\. A shared database or serving custom domain is a monthly item, first posted at a daily pass for the UTC month's remaining days\. AI calls, email, realm sign\-in codes and the router's data transfer post as they happen\. See live applications' recorded sizes, sleep settings, log refusals within the last day, and database connection limits\. A size change still in flight is not a recorded size\. This read changes nothing\.

## More about this action

The read takes no account argument and reads only the account your connection represents\. `balance` carries amounts as dollars strings and exact micro\-dollar integers\. Allowance and left are null when the allowance is Unset\. `left` excludes credit\. If the account has ever held credit, `credit_left` and `credit_left_micros` show what remains available now; `credit_drawn` and `credit_drawn_micros` show what this UTC month drew, whether or not it remains available\. These four members are one store snapshot and are absent otherwise, never null\. `state` is null for an unbilled account or an Unset allowance\.

From the same store snapshot, `credit_next_expiry_at` gives the earliest expiry among live grants\. It is present only while a live grant remains and is absent otherwise, never null\. Only the remaining credit in grants with that expiry expires then; later grants may remain\. No member identifies the amount expiring at that instant\.

Each `lines` row gives this month's quantity and micro\-dollar total, including closed and open days\. Its open values are part of those totals, not extra amounts\. `monthly` identifies a monthly item's line\. An account\-owned line has no application or environment\. After a UTC day ends, the daily pass closes it once a short grace past midnight has passed\. Late usage reopens it until the next pass\. A server's first day counts only its time awake, as on every other day\. The sum of `lines[].usd_micros` equals `balance.drawn_micros` plus `balance.credit_drawn_micros` plus `balance.shadow_micros` plus `balance.written_off_micros`, counting `credit_drawn_micros` as zero where absent, with open days included on both sides\. The balance, credit and lines are separate reads; usage posted between them can leave a temporary difference\.

With no size, sleep is null; otherwise production uses its recorded setting or size rule, and development sleeps\. Log refusals cover the last day; their first and latest UTC hours are null where none were refused\. The database connection limit is null when Unset, and the database member is null where there is no database\.

`model` is `usage` or `plans`, from the current pricing model\. Under `usage`, debits draw this month's free usage first; when `allowance` is set, `left` is the free usage remaining\. Credit covers the rest up to what the live grants hold, using grants in expiry order, earliest first\. Warning emails are sent\. The account can pause only when no live credit remains\. Under `plans`, usage is recorded in `shadow`, with no draw, warning email or pause\. Read `shadow` with `drawn` for usage recorded this month\.

## Access and action metadata

```json
{
  "name": "read_balance",
  "resource": "account",
  "tier": "observe",
  "surface": "account",
  "addresses": [
    "tzcloud",
    "tztools"
  ],
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "The connected account's balance, threshold and warning record, pause state, and usage lines for the current UTC month. Lines give monthly totals and their open-day parts by application, rate key and environment. Live applications give recorded size, environment sleep settings, log refusals within the last day, and the database connection limit per process. The answer includes the estate's pricing model. The read writes nothing.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_balance",
  "title": "Read account balance",
  "tier": "observe",
  "scenario": "CHI-L0-04",
  "summary": "Read your account's balance, warnings and pause state for this UTC month, with usage lines by application, rate key and environment. Awake time, stored data and transfer through the egress gateway or from storage areas post at the daily pass for the previous UTC day. Monthly items already held at the start of a UTC month post at that month's first daily pass. A shared database or serving custom domain is a monthly item, first posted at a daily pass for the UTC month's remaining days. AI calls, email, realm sign-in codes and the router's data transfer post as they happen. See live applications' recorded sizes, sleep settings, log refusals within the last day, and database connection limits. A size change still in flight is not a recorded size. This read changes nothing.",
  "owners": [
    "API-L0-27",
    "ACB-L0-98"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Additional properties: false |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","balance","state","lines","applications","model"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>reference | The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row\. Quote it when you report the call\.<br><br>Type: string<br>Pattern: ^\[0\-9a\-f\]\{10\}$ |
| /<wbr>properties/<wbr>balance | This UTC month's balance, with amounts as dollars strings and exact micro\-dollar integers\. Allowance and left are null when the allowance is Unset\.<br><br>The four credit amount members appear together if the account has ever held a grant and are absent otherwise, never null\. credit\_next\_expiry\_at appears only while a live grant remains\. The credit members are one store snapshot, separate from the other balance members and the threshold record; a debit between reads can leave a temporary difference\.<br><br>With no live credit, used is drawn\_micros and the base is allowance\_micros\. With credit\_left\_micros above zero, used is drawn\_micros plus credit\_drawn\_micros; the base is allowance\_micros plus credit\_drawn\_micros plus credit\_left\_micros\. No member gives either sum\. Add the exact micro\-dollar integers, not the rounded dollars strings\. On shadow, also add shadow\_micros to used\.<br><br>Type: object<br>Required fields: \["month","allowance\_micros","allowance","drawn\_micros","drawn","left\_micros","left","shadow\_micros","shadow","written\_off\_micros","written\_off"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>month | The first day of the UTC month the balance is for, as an ISO 8601 date\.<br><br>Type: string<br>Pattern: ^\[0\-9\]\{4\}\-\[0\-9\]\{2\}\-01$ |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>allowance\_micros | The UTC month's allowance as an exact integer of micro\-dollars; `null` where the allowance is Unset\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>allowance | The UTC month's allowance, from monthly\-free\-usage and any launch\-bonus row in effect at the month's first instant\. It is null, never zero, where monthly\-free\-usage has no row in effect\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>drawn\_micros | The amount drawn from the month's allowance, as an exact integer of micro\-dollars\.<br><br>Type: integer |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>drawn | What the account's debits have drawn from the month's allowance\.<br><br>Type: string |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>left\_micros | The allowance less the amount drawn, never below zero, as an exact integer of micro\-dollars; `null` where the allowance is Unset\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>left | What is left of the month's allowance: the allowance less what was drawn, never below zero\. `null` where the allowance is `null`\. An account marked unbilled reads its allowance whole\. This excludes credit\. Under `usage`, a billed account with a set allowance pauses only when both this amount and credit available to draw are used up\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>shadow\_micros | The amount kept as shadow, as an exact integer of micro\-dollars\.<br><br>Type: integer |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>shadow | Usage recorded but not drawn from the allowance\. It includes usage before the switch instant, usage with no switch instant in force, and an unbilled account's usage\. Under `plans`, all usage is shadow\. Each usage is judged by its own instant, never its posting's\.<br><br>Type: string |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>written\_off\_micros | The amount written off, as an exact integer of micro\-dollars\.<br><br>Type: integer |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>written\_off | What the account's debits did not draw from the month's allowance or credit, written off\. With a set allowance, usage beyond it draws credit available at its usage instant first; only the rest is written off\. A debit that would draw where the allowance is Unset is also written off\.<br><br>Type: string |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>credit\_left | Credit available to draw at this read, as a dollars string\. Present if the account has ever held credit, including used\-up or expired credit; omitted otherwise\. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places; a positive amount below one cent is rounded to four\.<br><br>Type: string |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>credit\_left\_micros | Credit available to draw at this read, as an exact integer of micro\-dollars\. Present if the account has ever held credit, including used\-up or expired credit; omitted otherwise\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>credit\_drawn | What this UTC month's usage drew from the account's credit, whether or not that credit is still available at this read, as a dollars string\. Present if the account has ever held credit, including used\-up or expired credit; omitted otherwise\. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places; a positive amount below one cent is rounded to four\.<br><br>Type: string |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>credit\_drawn\_micros | What this UTC month's usage drew from the account's credit, whether or not that credit is still available at this read, as an exact integer of micro\-dollars\. Present if the account has ever held credit, including used\-up or expired credit; omitted otherwise\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>balance/<wbr>properties/<wbr>credit\_next\_expiry\_at | The earliest expiry among live grants, in the grant's own UTC text to the millisecond\. Present only while a live grant remains; absent, never null, otherwise\. The instant applies to the remainders of grants expiring then\. It does not say that all credit\_left expires then; later grants can remain\. No member gives the amount expiring then\.<br><br>Type: string<br>Format: date\-time |
| /<wbr>properties/<wbr>state | This UTC month's threshold, warning and pause record; null for an unbilled account or an Unset allowance\.<br><br>Type: \["object","null"\]<br>Required fields: \["basis","month","reached","thresholds","recorded","paused","would\_pause","pause\_recorded\_at","paused\_until"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>basis | `enforced` under `usage`; `shadow` under `plans`, counting usage held as shadow beside usage drawn\. Nothing pauses on `shadow`\.<br><br>Type: string<br>Allowed values: \["enforced","shadow"\] |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>month | The first day of the current UTC month, as an ISO 8601 date\.<br><br>Type: string<br>Pattern: ^\[0\-9\]\{4\}\-\[0\-9\]\{2\}\-01$ |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>reached | The latest threshold reached this UTC month on this basis, read now; null if none\. With no live credit, it measures the month's free usage\. With live credit, it measures the whole balance defined by balance's amount\-used and base sums\. Under enforced it never reaches 100 while credit remains live\.<br><br>Type: \["integer","null"\]<br>Allowed values: \[50,80,100,null\] |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>thresholds | The thresholds up to reached, in order, on the same free\-usage or whole\-balance measure\. On shadow these are the thresholds that would have been reached, counting shadow usage too\. A recorded warning can stand for a threshold no longer in this list after a grant raises the base\.<br><br>Type: array |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>thresholds/<wbr>items | Type: integer<br>Allowed values: \[50,80,100\] |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>recorded | Warnings\-pass recordings for this UTC month and basis, in threshold order\. On enforced a warning email covered each; on shadow an email would have covered each\. One email may cover several\. At the next pass after a purchase, recordings made before its grant's own instant are removed; a threshold reached again can be recorded again\. An operator's grant removes none\. Until that pass runs, earlier recordings remain\.<br><br>Type: array |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>recorded/<wbr>items | Type: object<br>Required fields: \["threshold","at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>recorded/<wbr>items/<wbr>properties/<wbr>threshold | The threshold the pass recorded\.<br><br>Type: integer<br>Allowed values: \[50,80,100\] |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>recorded/<wbr>items/<wbr>properties/<wbr>at | The instant the pass recorded this threshold\.<br><br>Type: string<br>Format: date\-time |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>paused | Whether the account is paused now; always `false` on `shadow`\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>would\_pause | On shadow, whether usage drawn and held as shadow has reached the whole of the account's measure: free usage without live credit, or the whole balance with it\. Always false on enforced\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>pause\_recorded\_at | The instant the pass recorded threshold 100 on this basis, or null where no such recording is held\. It dates the recording, not the start of a current pause\. An operator's grant can end a pause while this instant remains\. After a purchase, the earlier recording remains until the next pass removes it\.<br><br>Type: \["string","null"\]<br>Format: date\-time |
| /<wbr>properties/<wbr>state/<wbr>properties/<wbr>paused\_until | The first instant of the next UTC month only where paused or would\_pause is true; null otherwise\. On enforced, an account with live credit is not paused and this is null\. A live grant can end a pause before that date\.<br><br>Type: \["string","null"\]<br>Format: date\-time |
| /<wbr>properties/<wbr>lines | This month's totals by application, rate key and environment, including closed and open days\. Open values are part of those totals\.<br><br>Type: array |
| /<wbr>properties/<wbr>lines/<wbr>items | Type: object<br>Additional properties: false<br>Required fields: \["application","rate\_key","environment","quantity","usd\_micros","open\_quantity","open\_usd\_micros","monthly"\] |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>application | The application id, matching applications\[\]\.id and list\_applications, or null for an account\-owned line\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>rate\_key | The stable, readable, hyphenated name of the metered item, unchanged across months\. The public pricing page explains each charged line: /pricing/\.<br><br>Type: string |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>environment | The environment, or null for an account\-owned line\.<br><br>Allowed values: \["production","development",null\] |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>quantity | This month's quantity, closed and open days together\. Unit by rate key: shared server seconds awake, days charged for monthly items \(dedicated servers included\), storage byte\-days, transfer bytes, counts, or AI provider cost in micro\-dollars\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>usd\_micros | This month's exact micro\-dollar total, closed and open days together\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>open\_quantity | Quantity from days not yet closed, included in `quantity`, in that rate key's same unit\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>open\_usd\_micros | The micro\-dollar amount from days not yet closed, included in usd\_micros\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>lines/<wbr>items/<wbr>properties/<wbr>monthly | Whether this is a monthly item's line\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications | Your account's live applications and their recorded settings\.<br><br>Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items | Type: object<br>Additional properties: false<br>Required fields: \["id","name","size","environments","database"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>id | The application id, also returned by list\_applications and each usage line's application member\.<br><br>Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>name | The application's name\.<br><br>Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size | The recorded size, or null\. A size change still in flight is excluded\.<br><br>Allowed values: \["shared\-0\.5gb","shared\-1gb",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments | One row per environment the application has, production first\.<br><br>Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items | Type: object<br>Additional properties: false<br>Required fields: \["name","sleeps","logs\_refused"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>name | The environment: production or development\.<br><br>Allowed values: \["production","development"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>sleeps | `true` where the environment's compute stops when idle\. Where a size is held, production follows its recorded sleep setting or size rule, and development is `true`\. Null where no size is held\.<br><br>Type: \["boolean","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>logs\_refused | Log batches refused within the last 24 hours at `log-retained-capacity`, the retained\-bytes bound\. A write then refuses `log_capacity_reached` \(409\)\.<br><br>Type: object<br>Additional properties: false<br>Required fields: \["refused","first\_hour","latest\_hour"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>logs\_refused/<wbr>properties/<wbr>refused | The number of log batches refused at the retained\-bytes bound within the last 24 hours, one count per batch\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>logs\_refused/<wbr>properties/<wbr>first\_hour | The start of the UTC hour of the first refusal in that window, or null where none occurred\.<br><br>Type: \["string","null"\]<br>Format: date\-time |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>environments/<wbr>items/<wbr>properties/<wbr>logs\_refused/<wbr>properties/<wbr>latest\_hour | The start of the UTC hour of the latest refusal in that window, or null where none occurred\.<br><br>Type: \["string","null"\]<br>Format: date\-time |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>database | Null where the application has no database\. Otherwise gives the connection limit each process receives\.<br><br> |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>database/<wbr>oneOf/<wbr>0 | Type: null |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>database/<wbr>oneOf/<wbr>1 | Type: object<br>Additional properties: false<br>Required fields: \["connections\_per\_process"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>database/<wbr>oneOf/<wbr>1/<wbr>properties/<wbr>connections\_per\_process | The served database connection limit each process holds; null when that limit is Unset\.<br><br>Type: \["integer","null"\]<br>Minimum: 0 |
| /<wbr>properties/<wbr>model | `usage` or `plans`, from the current pricing model\. Under `usage`, debits draw this month's free usage first; when `allowance` is set, `left` is the free usage remaining\. Credit covers the rest up to what the live grants hold, using grants in expiry order, earliest first\. Warning emails are sent\. The account can pause only when no live credit remains\. Under `plans`, usage is recorded in `shadow`, with no draw, warning email or pause\. Read `shadow` with `drawn` for usage recorded this month\.<br><br>Allowed values: \["plans","usage"\] |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {},
    "additionalProperties": false
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "balance",
      "state",
      "lines",
      "applications",
      "model"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded your call under: ten lowercase hexadecimal characters, the value in the call’s record row. Quote it when you report the call."
      },
      "balance": {
        "type": "object",
        "required": [
          "month",
          "allowance_micros",
          "allowance",
          "drawn_micros",
          "drawn",
          "left_micros",
          "left",
          "shadow_micros",
          "shadow",
          "written_off_micros",
          "written_off"
        ],
        "additionalProperties": false,
        "description": "This UTC month's balance, with amounts as dollars strings and exact micro-dollar integers. Allowance and left are null when the allowance is Unset.\n\nThe four credit amount members appear together if the account has ever held a grant and are absent otherwise, never null. credit_next_expiry_at appears only while a live grant remains. The credit members are one store snapshot, separate from the other balance members and the threshold record; a debit between reads can leave a temporary difference.\n\nWith no live credit, used is drawn_micros and the base is allowance_micros. With credit_left_micros above zero, used is drawn_micros plus credit_drawn_micros; the base is allowance_micros plus credit_drawn_micros plus credit_left_micros. No member gives either sum. Add the exact micro-dollar integers, not the rounded dollars strings. On shadow, also add shadow_micros to used.",
        "properties": {
          "month": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-01$",
            "description": "The first day of the UTC month the balance is for, as an ISO 8601 date."
          },
          "allowance_micros": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The UTC month's allowance as an exact integer of micro-dollars; `null` where the allowance is Unset."
          },
          "allowance": {
            "type": [
              "string",
              "null"
            ],
            "description": "The UTC month's allowance, from monthly-free-usage and any launch-bonus row in effect at the month's first instant. It is null, never zero, where monthly-free-usage has no row in effect."
          },
          "drawn_micros": {
            "type": "integer",
            "description": "The amount drawn from the month's allowance, as an exact integer of micro-dollars."
          },
          "drawn": {
            "type": "string",
            "description": "What the account's debits have drawn from the month's allowance."
          },
          "left_micros": {
            "type": [
              "integer",
              "null"
            ],
            "description": "The allowance less the amount drawn, never below zero, as an exact integer of micro-dollars; `null` where the allowance is Unset."
          },
          "left": {
            "type": [
              "string",
              "null"
            ],
            "description": "What is left of the month's allowance: the allowance less what was drawn, never below zero. `null` where the allowance is `null`. An account marked unbilled reads its allowance whole. This excludes credit. Under `usage`, a billed account with a set allowance pauses only when both this amount and credit available to draw are used up."
          },
          "shadow_micros": {
            "type": "integer",
            "description": "The amount kept as shadow, as an exact integer of micro-dollars."
          },
          "shadow": {
            "type": "string",
            "description": "Usage recorded but not drawn from the allowance. It includes usage before the switch instant, usage with no switch instant in force, and an unbilled account's usage. Under `plans`, all usage is shadow. Each usage is judged by its own instant, never its posting's."
          },
          "written_off_micros": {
            "type": "integer",
            "description": "The amount written off, as an exact integer of micro-dollars."
          },
          "written_off": {
            "type": "string",
            "description": "What the account's debits did not draw from the month's allowance or credit, written off. With a set allowance, usage beyond it draws credit available at its usage instant first; only the rest is written off. A debit that would draw where the allowance is Unset is also written off."
          },
          "credit_left": {
            "type": "string",
            "description": "Credit available to draw at this read, as a dollars string. Present if the account has ever held credit, including used-up or expired credit; omitted otherwise. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places; a positive amount below one cent is rounded to four."
          },
          "credit_left_micros": {
            "type": "integer",
            "minimum": 0,
            "description": "Credit available to draw at this read, as an exact integer of micro-dollars. Present if the account has ever held credit, including used-up or expired credit; omitted otherwise."
          },
          "credit_drawn": {
            "type": "string",
            "description": "What this UTC month's usage drew from the account's credit, whether or not that credit is still available at this read, as a dollars string. Present if the account has ever held credit, including used-up or expired credit; omitted otherwise. A dollars string starts with a dollar sign, separates thousands with commas and is rounded to two decimal places; a positive amount below one cent is rounded to four."
          },
          "credit_drawn_micros": {
            "type": "integer",
            "minimum": 0,
            "description": "What this UTC month's usage drew from the account's credit, whether or not that credit is still available at this read, as an exact integer of micro-dollars. Present if the account has ever held credit, including used-up or expired credit; omitted otherwise."
          },
          "credit_next_expiry_at": {
            "type": "string",
            "format": "date-time",
            "description": "The earliest expiry among live grants, in the grant's own UTC text to the millisecond. Present only while a live grant remains; absent, never null, otherwise. The instant applies to the remainders of grants expiring then. It does not say that all credit_left expires then; later grants can remain. No member gives the amount expiring then."
          }
        }
      },
      "state": {
        "type": [
          "object",
          "null"
        ],
        "required": [
          "basis",
          "month",
          "reached",
          "thresholds",
          "recorded",
          "paused",
          "would_pause",
          "pause_recorded_at",
          "paused_until"
        ],
        "additionalProperties": false,
        "description": "This UTC month's threshold, warning and pause record; null for an unbilled account or an Unset allowance.",
        "properties": {
          "basis": {
            "type": "string",
            "enum": [
              "enforced",
              "shadow"
            ],
            "description": "`enforced` under `usage`; `shadow` under `plans`, counting usage held as shadow beside usage drawn. Nothing pauses on `shadow`."
          },
          "month": {
            "type": "string",
            "pattern": "^[0-9]{4}-[0-9]{2}-01$",
            "description": "The first day of the current UTC month, as an ISO 8601 date."
          },
          "reached": {
            "type": [
              "integer",
              "null"
            ],
            "enum": [
              50,
              80,
              100,
              null
            ],
            "description": "The latest threshold reached this UTC month on this basis, read now; null if none. With no live credit, it measures the month's free usage. With live credit, it measures the whole balance defined by balance's amount-used and base sums. Under enforced it never reaches 100 while credit remains live."
          },
          "thresholds": {
            "type": "array",
            "items": {
              "type": "integer",
              "enum": [
                50,
                80,
                100
              ]
            },
            "description": "The thresholds up to reached, in order, on the same free-usage or whole-balance measure. On shadow these are the thresholds that would have been reached, counting shadow usage too. A recorded warning can stand for a threshold no longer in this list after a grant raises the base."
          },
          "recorded": {
            "type": "array",
            "description": "Warnings-pass recordings for this UTC month and basis, in threshold order. On enforced a warning email covered each; on shadow an email would have covered each. One email may cover several. At the next pass after a purchase, recordings made before its grant's own instant are removed; a threshold reached again can be recorded again. An operator's grant removes none. Until that pass runs, earlier recordings remain.",
            "items": {
              "type": "object",
              "required": [
                "threshold",
                "at"
              ],
              "additionalProperties": false,
              "properties": {
                "threshold": {
                  "type": "integer",
                  "enum": [
                    50,
                    80,
                    100
                  ],
                  "description": "The threshold the pass recorded."
                },
                "at": {
                  "type": "string",
                  "format": "date-time",
                  "description": "The instant the pass recorded this threshold."
                }
              }
            }
          },
          "paused": {
            "type": "boolean",
            "description": "Whether the account is paused now; always `false` on `shadow`."
          },
          "would_pause": {
            "type": "boolean",
            "description": "On shadow, whether usage drawn and held as shadow has reached the whole of the account's measure: free usage without live credit, or the whole balance with it. Always false on enforced."
          },
          "pause_recorded_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The instant the pass recorded threshold 100 on this basis, or null where no such recording is held. It dates the recording, not the start of a current pause. An operator's grant can end a pause while this instant remains. After a purchase, the earlier recording remains until the next pass removes it."
          },
          "paused_until": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "The first instant of the next UTC month only where paused or would_pause is true; null otherwise. On enforced, an account with live credit is not paused and this is null. A live grant can end a pause before that date."
          }
        }
      },
      "lines": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "application",
            "rate_key",
            "environment",
            "quantity",
            "usd_micros",
            "open_quantity",
            "open_usd_micros",
            "monthly"
          ],
          "properties": {
            "application": {
              "type": [
                "string",
                "null"
              ],
              "description": "The application id, matching applications[].id and list_applications, or null for an account-owned line."
            },
            "rate_key": {
              "type": "string",
              "description": "The stable, readable, hyphenated name of the metered item, unchanged across months. The public pricing page explains each charged line: /pricing/."
            },
            "environment": {
              "enum": [
                "production",
                "development",
                null
              ],
              "description": "The environment, or null for an account-owned line."
            },
            "quantity": {
              "type": "integer",
              "minimum": 0,
              "description": "This month's quantity, closed and open days together. Unit by rate key: shared server seconds awake, days charged for monthly items (dedicated servers included), storage byte-days, transfer bytes, counts, or AI provider cost in micro-dollars."
            },
            "usd_micros": {
              "type": "integer",
              "minimum": 0,
              "description": "This month's exact micro-dollar total, closed and open days together."
            },
            "open_quantity": {
              "type": "integer",
              "minimum": 0,
              "description": "Quantity from days not yet closed, included in `quantity`, in that rate key's same unit."
            },
            "open_usd_micros": {
              "type": "integer",
              "minimum": 0,
              "description": "The micro-dollar amount from days not yet closed, included in usd_micros."
            },
            "monthly": {
              "type": "boolean",
              "description": "Whether this is a monthly item's line."
            }
          }
        },
        "description": "This month's totals by application, rate key and environment, including closed and open days. Open values are part of those totals."
      },
      "applications": {
        "type": "array",
        "items": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "id",
            "name",
            "size",
            "environments",
            "database"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The application id, also returned by list_applications and each usage line's application member."
            },
            "name": {
              "type": "string",
              "description": "The application's name."
            },
            "size": {
              "enum": [
                "shared-0.5gb",
                "shared-1gb",
                null
              ],
              "description": "The recorded size, or null. A size change still in flight is excluded."
            },
            "environments": {
              "type": "array",
              "description": "One row per environment the application has, production first.",
              "items": {
                "type": "object",
                "additionalProperties": false,
                "required": [
                  "name",
                  "sleeps",
                  "logs_refused"
                ],
                "properties": {
                  "name": {
                    "enum": [
                      "production",
                      "development"
                    ],
                    "description": "The environment: production or development."
                  },
                  "sleeps": {
                    "type": [
                      "boolean",
                      "null"
                    ],
                    "description": "`true` where the environment's compute stops when idle. Where a size is held, production follows its recorded sleep setting or size rule, and development is `true`. Null where no size is held."
                  },
                  "logs_refused": {
                    "type": "object",
                    "additionalProperties": false,
                    "required": [
                      "refused",
                      "first_hour",
                      "latest_hour"
                    ],
                    "description": "Log batches refused within the last 24 hours at `log-retained-capacity`, the retained-bytes bound. A write then refuses `log_capacity_reached` (409).",
                    "properties": {
                      "refused": {
                        "type": "integer",
                        "minimum": 0,
                        "description": "The number of log batches refused at the retained-bytes bound within the last 24 hours, one count per batch."
                      },
                      "first_hour": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time",
                        "description": "The start of the UTC hour of the first refusal in that window, or null where none occurred."
                      },
                      "latest_hour": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "format": "date-time",
                        "description": "The start of the UTC hour of the latest refusal in that window, or null where none occurred."
                      }
                    }
                  }
                }
              }
            },
            "database": {
              "description": "Null where the application has no database. Otherwise gives the connection limit each process receives.",
              "oneOf": [
                {
                  "type": "null"
                },
                {
                  "type": "object",
                  "additionalProperties": false,
                  "required": [
                    "connections_per_process"
                  ],
                  "properties": {
                    "connections_per_process": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "minimum": 0,
                      "description": "The served database connection limit each process holds; null when that limit is Unset."
                    }
                  }
                }
              ]
            }
          }
        },
        "description": "Your account's live applications and their recorded settings."
      },
      "model": {
        "enum": [
          "plans",
          "usage"
        ],
        "description": "`usage` or `plans`, from the current pricing model. Under `usage`, debits draw this month's free usage first; when `allowance` is set, `left` is the free usage remaining. Credit covers the rest up to what the live grants hold, using grants in expiry order, earliest first. Warning emails are sent. The account can pause only when no live credit remains. Under `plans`, usage is recorded in `shadow`, with no draw, warning email or pause. Read `shadow` with `drawn` for usage recorded this month."
      }
    }
  }
}
```

## Shared contracts

- [Refusals](/cloud/reference/refusals/): every refusal, by surface, with its cause and its remedy
- [schemas/wire\_error\.schema\.json](/cloud/reference/sources/schemas/wire-error-schema/)
- [schemas/wire\_errors\.json](/cloud/reference/sources/schemas/wire-errors/)
- [schemas/action\_payloads\.json](/cloud/reference/sources/schemas/action-payloads/) (includes shared shapes)
- [management\_api\_contract\.md](/cloud/reference/sources/management-api-contract/)
