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

# read\_usage

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

A script calls this action over HTTPS at `POST https://tzcloud.turnzero.ai/v1/read_usage`, 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 `tzcloud_read_usage`.

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 this UTC month's usage for your applications\. Each gives its `label` and `size`\. Compare `month_total` with `quota`\. Add nothing\. `includes_before` gives each source's timestamp\. Later router activity may already count\. Read `freshness` before comparing recent requests\.

An application's `state` is its worst measure state, or `unknown` until recorded\. For a size, only stored data has an overall usage quantity\. An over reading refuses file puts, new uploads and the other operations listed in the reference\. This lasts until the next successful daily check or a raised quantity\. Reads and changes of size continue\.

## More about this action

The `wait_seconds` argument delays the read until 1 to 45 seconds after the call arrived, then composes the answer from reads made after the hold\. Nothing in flight can end this hold early\. The answer includes `waited_ms`, the milliseconds held, and no `settled`\. Without the argument, the read returns at once\. The router sends counts once a minute\. Requests under two minutes old may not be counted yet, so one wait may not be enough\. Compare `includes_before.router` with the time of your requests before calling again\. A process holds one usage read per account and fifty held reads in all; a read beyond either returns at once\. A shutdown releases the hold, and your connection's close ends it\.

The router sends its counts once a minute\. A read soon after a request may not count it yet, and the request can show first in the per\-minute router records of `read_logs`\. A count the router cannot send, because a send failed or the router stopped abruptly, is never added\. For stored data over quota, file puts on bound areas, a new deploy's upload, `deploy_files` with file contents or a stored entry, and `generate_image` naming that application are refused until the next successful daily check or a raised quantity\. Both sizes have the same stored\-data ceiling\.

After each deploy that ends `deployed`, the plane attempts a first check while no check is recorded; the daily pass attempts a check once a day\. No measurement runs on demand, because the stored\-data reading lists every file in the application's storage areas, a cost anyone could repeat\.

Each `applications` entry gives its `label` and `size`\. Compare `month_total` with `quota`\. For traffic, the total includes this month's router counts and the check's terms when the check ran this month\. Stored data gives the last check's reading, or null before that check\. Other measures give their reading at the call\. The `quota` member is the size's quantity for the measure, or null where the size has none\. Backend actions, data transfer, the AI allowance and email by the month have no quantity for a size\.

`includes_before` lists only the sources in `month_total`, each with its ISO 8601 UTC instant\. On the two traffic measures, `router` is two minutes before the read or the application's `created_at`, whichever is later\. `daily_check` is the application's `checked_at` only where that check falls in the answered month; otherwise that key is absent\. Stored data carries `daily_check` whenever a check has run, even in an earlier month; it marks the check that composed the figure\. Database size samples used by that check may be older\.

If `month_total` is null, `includes_before` is null\. The allowance, push messages and email recipients carry `read` when read at the call; otherwise the map is null\. A source key is never null\. Router activity before `router` is included, barring a lost report; later router activity may already count\. Daily\-check activity after `checked_at` is added at the next check\.

Backend actions count one per request the serving router forwards to the application's backend, scheduled runs included\. They also count one per data message a client sends on a WebSocket, plus each end\-user sign\-in and each session verification the accounts service performs\. A request the router verifies itself counts once\. The router sends counts once a minute, including WebSocket messages\. Requests and messages under two minutes old may not yet count in `month_total`\. Sign\-ins and verifications are counted at the daily check\.

An application's `state` is the worst of its measures' states\. It reads `unknown` until a state is recorded, even when each measure reads `ok`\. The `state` member is recomputed for backend actions, data transfer, and stored data: `ok`, `warning` from 80%, `over` at or above quota, and `unset`\. Where backend actions or data transfer has a quantity, once its state is `over`, the serving router returns 429 `usage_over_quota` on every application request and scheduled run until `resets_at`, the next UTC month's first instant\. Reads and changes of size continue\.

Where one of the three measures has no state recorded yet, its state reads `unknown` where `month_total` is null\. Otherwise it reads `unset` where `quota` is null, `ok` below 80% of quota, and `unknown` in every other case\.

The `refuses` member says what an `over` state refuses: `requests`, `file_puts`, `ai_calls`, `push_sends`, or `email_sends`\. It is null where nothing is refused\.

## Access and action metadata

```json
{
  "name": "read_usage",
  "resource": "application",
  "tier": "observe",
  "surface": "tzcloud",
  "addresses": [
    "tzcloud"
  ],
  "product": "cloud",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "Read the application's UTC-month usage for backend actions, data transfer, stored data, the AI allowance, push messages and email recipients. Each measure gives `month_total`, source timestamps in `includes_before`, `state`, `resets_at` where a refusal ends, and `refuses`. Its `quota` is the size's quantity where it has one: stored data and push messages. It is null for backend actions, data transfer, the AI allowance and email by the month. The states are `ok`, `warning`, `over`, `unset` and `unknown`. After a successful deploy, the plane attempts the first check if the application has no recorded check. Backend actions count one per request the serving router forwards to the application's backend, a scheduled run among them, one per data message a client sends on a WebSocket, plus each end-user sign-in and each session verification the accounts service performs. A request the router verifies itself counts once. The router's count reaches `month_total` in a minute (a WebSocket message's in two), sign-ins and verifications at the daily check. For traffic, the total includes this month's router counts and the check's terms when the check ran this month. Stored data gives the last check's reading, or null before that check. The AI allowance, push messages and email recipients give their reading at the call. Add nothing to `month_total`. A backend actions, data transfer, or stored data measure with no recorded state reads `unknown` where `month_total` is null, else `unset` where `quota` is null, `ok` below 80% of `quota`, and `unknown` otherwise. The two traffic states are recomputed on each router report the control plane folds, and the stored-data state at each check. An over state refuses by name. Where a traffic quantity applies, an over traffic state makes the serving router refuse application requests with 429 `usage_over_quota` until the next UTC month's first instant. No size has a traffic quantity. The object storage surface refuses file puts on bound areas until the next successful daily pass or a raised quantity. Meanwhile reads and changes of size continue, but over stored data also refuses a new deploy's upload, `deploy_files` with file contents or a stored entry, and `generate_image` with `application` set to that application. With no application given, it reads every live application of the account. The AI allowance, push messages and email recipients are counted at each call or send, each state computed at the read and joining no overall state. An `over` month state refuses the corresponding calls or sends until the next UTC month's first instant. Where their count was read, email recipients also give hour and day counts with their own quotas and reset instants. `refuses` is `requests`, `file_puts`, `ai_calls`, `push_sends`, or `email_sends`.\n\nEach application's `egress_limits` member reads its outbound limits: `connections_per_minute` (per tunnel proxy replica), `bytes_per_day`, `bytes_today`, `refused_today`, `state` (`ok`, `capped`, or `unset`), and `resets_at`, the next UTC day's first instant. An Unset limit is no bound, and `state` reads `unset`.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": false,
    "idempotentHint": true
  }
}
```

## MCP catalog entry

```json
{
  "name": "read_usage",
  "title": "Read usage",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "Read this UTC month's usage for your applications. Each gives its `label` and `size`. Compare `month_total` with `quota`. Add nothing. `includes_before` gives each source's timestamp. Later router activity may already count. Read `freshness` before comparing recent requests.\n\nAn application's `state` is its worst measure state, or `unknown` until recorded. For a size, only stored data has an overall usage quantity. An over reading refuses file puts, new uploads and the other operations listed in the reference. This lasts until the next successful daily check or a raised quantity. Reads and changes of size continue.",
  "owners": [
    "ACB-L0-26"
  ]
}
```

## request

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object |
| /<wbr>properties/<wbr>application | One application id; omit it for all your live applications\.<br><br>Type: string |
| /<wbr>properties/<wbr>wait\_seconds | Seconds to delay this read\. Router requests under two minutes old may not be counted\. Read again once two minutes have passed since your last router request\.<br><br>Type: integer<br>Minimum: 1<br>Maximum: 45 |

## response

| JSON pointer | Description and constraints |
|---|---|
| "" \(root\) | Type: object<br>Required fields: \["contract\_version","period","warning\_fraction","applications"\] |
| /<wbr>properties/<wbr>contract\_version | Required value: 1 |
| /<wbr>properties/<wbr>waited\_ms | Present where the request carried `wait_seconds`: the milliseconds the answer was held before its reads\.<br><br>Type: integer<br>Minimum: 0 |
| /<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>period | the UTC calendar month the counts belong to, YYYY\-MM<br><br>Type: string<br>Pattern: ^\[0\-9\]\{4\}\-\[0\-9\]\{2\}$ |
| /<wbr>properties/<wbr>freshness | How soon recent activity reaches the figures\. Activity since a source timestamp may not be counted yet; later router activity may already be included\.<br><br>Type: string |
| /<wbr>properties/<wbr>warning\_fraction | the warning threshold as a fraction of each measure's quantity \(low\-capacity\-warning\)<br><br>Type: number |
| /<wbr>properties/<wbr>applications | Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items | Type: object<br>Required fields: \["id","label","state","state\_since","checked\_at","measures","egress\_limits"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>id | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>label | Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size |  |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size/<wbr>anyOf/<wbr>0 | $ref: \#/shapes/app\_size |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>size/<wbr>anyOf/<wbr>1 | Type: null |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>unlimited | True on the company's own applications, where `size` is null\. Absent on every other application\.<br><br>Type: boolean |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>state | the worst recorded measure state as read now; unknown until a state is recorded<br><br>Type: string<br>Allowed values: \["ok","warning","over","unset","unknown"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>state\_since | Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>checked\_at | the last check's stamp, the check a deploy runs where none is recorded, or the daily check; null before the first check\. A router report can record a state before the first check, when the traffic totals come from this month's router counts\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>note | Present only where `checked_at` is null\. It says the first daily check has not run or gives the time of a failed check\. The check runs within a day\. Until a check succeeds, traffic totals come from this month's router counts and stored data is not yet sampled\.<br><br>Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures | Type: object<br>Required fields: \["backend\_actions","data\_transfer\_bytes","stored\_data\_bytes","ai\_allowance\_usd\_micros","push\_messages","email\_recipients","function\_calls"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>backend\_actions | One unit per request the serving router forwards to the application's backend, a scheduled run among them, one per data message a client sends on a WebSocket, plus each end\-user sign\-in and each session verification the accounts service performs\. A request the router verifies itself counts once, and the work inside a request is not counted again\. The router sends counts once a minute, including WebSocket messages\. Requests and messages under two minutes old may not yet count in `month_total`\. Sign\-ins and verifications reach the measure at the daily check\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>backend\_actions/<wbr>properties/<wbr>refuses | Allowed values: \["requests","file\_puts",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>data\_transfer\_bytes | $ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>data\_transfer\_bytes/<wbr>properties/<wbr>refuses | Allowed values: \["requests","file\_puts",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>stored\_data\_bytes | Over, it refuses `file_puts`: the file puts on the application's bound storage areas, which the object storage surface refuses by the same name\. No usage state refuses the application's calls of the platform upstream issue\-tracking at the egress gateway, its writes and its reads alike\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>stored\_data\_bytes/<wbr>properties/<wbr>refuses | Allowed values: \["requests","file\_puts",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>ai\_allowance\_usd\_micros | Read live at the call: `month_total` is the included AI allowance's micro\-dollars drawn this UTC month, 1,000,000 to the dollar, from the platform upstream's drawn rows, a passed call's or a forwarded call's ended early\. Each row uses its model's rates in effect at the call if the platform prices it\. Otherwise it uses the rates then in effect from the row with the highest base output rate\. For a size, `quota` is null and `state` never reads `over`\. AI draws your account's balance; read `read_balance` for what is drawn and left\. It joins no overall state, because a drawn allowance stops allowance calls and nothing else\. Where an allowance quantity applies, an over reading refuses `ai_calls`: the egress gateway refuses the application's ai\-allowance calls 429 allowance\_exhausted\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>ai\_allowance\_usd\_micros/<wbr>properties/<wbr>refuses | Allowed values: \["ai\_calls",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>push\_messages | Counted at the send in the application's month row and read at the call: `month_total` is the deliveries the push service accepted for the application this UTC month, one per device a send accepted, every environment counted\. The `quota` is the size's served `push-messages-capacity` quantity, a count of accepted deliveries\. It joins no overall state, because a spent quantity stops the application's sends and nothing else\. Over, it refuses `push_sends`: the push service refuses the application's sends 429 usage\_over\_quota\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>push\_messages/<wbr>properties/<wbr>refuses | Allowed values: \["push\_sends",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>email\_recipients | Counted at the send in the application's counter rows and read at the call: `month_total` is the recipients the email service's accepted sends addressed this UTC month, `to` and `cc` together, every environment counted\. The month's `quota` is null for a size\. Where a monthly quantity applies, spending it stops only the application's email sends\. An over reading refuses `email_sends` as `email_limit_reached`\. Beside the base members, `hour` and `day` carry the same count for the current UTC hour and day against `email-recipients-per-hour` and `email-recipients-per-day`, at which the send route also refuses\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>email\_recipients/<wbr>properties/<wbr>refuses | Allowed values: \["email\_sends",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>email\_recipients/<wbr>properties/<wbr>hour | $ref: \#/shapes/email\_period |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>email\_recipients/<wbr>properties/<wbr>day | $ref: \#/shapes/email\_period |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>measures/<wbr>properties/<wbr>function\_calls | `month_total` is the application's function calls reported this UTC month, both environments together\. `router` is the only key in `includes_before`; `by_environment` splits the routed rows from their first day this month and is null if no routed row has an environment this month\. `quota`, `resets_at` and `refuses` are null, and `state` is `unset`: calls are charged at the `function-calls` rate, not refused on a count\. A function's request adds no backend action\.<br><br>$ref: \#/shapes/usage\_measure |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits | The application's outbound limits for the current UTC day, served from its size's quantity rows and counted for the whole application\. The tunnel proxy refuses a connection past either limit and cuts open connections past the day limit; the gateway refuses calls to the application's own upstreams past it\. A limit whose cell is Unset is no bound\.<br><br>Type: object<br>Required fields: \["connections\_per\_minute","bytes\_per\_day","bytes\_today","refused\_today","state","resets\_at"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>connections\_per\_minute | The outbound connections the application may open per UTC minute on one tunnel proxy replica, or null where the size's cell is Unset\. Both sizes have the same quantity\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>bytes\_per\_day | The bytes the application's outbound connections and its own upstream calls may carry per UTC day, both ways, or null where the size's cell is Unset\. Both sizes have the same quantity\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>bytes\_today | The bytes counted so far today, in UTC, for the whole application; the figure lags the wire by the flush intervals the concepts page states\.<br><br>Type: integer |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>refused\_today | The connections and calls refused at either limit so far today, in UTC\.<br><br>Type: integer |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>state | `ok` under the day limit, `capped` at or past it, `unset` where the day limit's cell is Unset\.<br><br>Type: string<br>Allowed values: \["ok","capped","unset"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>egress\_limits/<wbr>properties/<wbr>resets\_at | The first instant of the next UTC day, when the day's figures reset, in ISO 8601 form\.<br><br>Type: string |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits | One row per size quantity the measures and egress\_limits above do not cover, and per environment where the quantity counts each environment apart\. A quantity retired for sizes has no row\. A count is null where read\_usage reads no count for the application, as for database connections\. The deploy count covers the rolling last 24 hours\.<br><br>Type: array |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items | Type: object<br>Required fields: \["quantity","environment","limit","count","resets\_at"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>quantity | The quantity's entry name in the pricing registry, as read\_plan\_quotas gives it\.<br><br>Type: string<br>Allowed values: \["database\-connection\-limit","schedule\-minimum\-interval","schedule\-count\-limit","deploys\-per\-day","log\-retained\-capacity","development\-halt\-after\-days","development\-realm\-account\-limit","signin\-code\-sends\-per\-hour","websocket\-connections\-per\-replica","free\-socket\-hours\-per\-month"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>environment | The environment the row counts, or null where the quantity is the whole application's\.<br><br>Allowed values: \["development","production",null\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>limit | The size's cell, in the unit read\_plan\_quotas gives, or null where the cell is Unset; where a cell is unset and a default applies, the quantity's own page gives it\.<br><br>Type: \["integer","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>count | The platform's current count in that unit, or null where read\_usage reads no count for the application or its read failed\.<br><br>Type: \["integer","null"\]<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>resets\_at | The instant the count next resets, in ISO 8601 form, or null where no fixed instant resets it\.<br><br>Type: \["string","null"\] |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>limits/<wbr>items/<wbr>properties/<wbr>harness\_count | On the log\-retained\-capacity row alone: the bytes of the harness's entries the environment holds, which the same limit bounds apart from the count of the application's own entries, or null where its read failed\.<br><br>Type: \["integer","null"\]<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs | Present on an application with one environment where development's records hold or drew anything this month\. The figures count inside the measures above and add no charge\.<br><br>Type: object<br>Required fields: \["environment","egress\_request\_bytes","storage\_get\_bytes","database\_size\_bytes","detail"\]<br>Additional properties: false |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs/<wbr>properties/<wbr>environment | Required value: development |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs/<wbr>properties/<wbr>egress\_request\_bytes | Bytes sent through the egress gateway under the development credential this month\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs/<wbr>properties/<wbr>storage\_get\_bytes | Bytes read from the development partitions of the application's storage areas this month\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs/<wbr>properties/<wbr>database\_size\_bytes | The development database's size at its last sample\.<br><br>Type: integer<br>Minimum: 0 |
| /<wbr>properties/<wbr>applications/<wbr>items/<wbr>properties/<wbr>local\_runs/<wbr>properties/<wbr>detail | One sentence giving the three figures\.<br><br>Type: string |
| /<wbr>properties/<wbr>detail | Type: string |
| /<wbr>properties/<wbr>page | $ref: \#/shapes/page |

## Complete payload contract

```json
{
  "request": {
    "type": "object",
    "properties": {
      "application": {
        "type": "string",
        "description": "One application id; omit it for all your live applications."
      },
      "wait_seconds": {
        "type": "integer",
        "minimum": 1,
        "maximum": 45,
        "description": "Seconds to delay this read. Router requests under two minutes old may not be counted. Read again once two minutes have passed since your last router request."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "period",
      "warning_fraction",
      "applications"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "waited_ms": {
        "type": "integer",
        "minimum": 0,
        "description": "Present where the request carried `wait_seconds`: the milliseconds the answer was held before its reads."
      },
      "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."
      },
      "period": {
        "type": "string",
        "pattern": "^[0-9]{4}-[0-9]{2}$",
        "description": "the UTC calendar month the counts belong to, YYYY-MM"
      },
      "freshness": {
        "type": "string",
        "description": "How soon recent activity reaches the figures. Activity since a source timestamp may not be counted yet; later router activity may already be included."
      },
      "warning_fraction": {
        "type": "number",
        "description": "the warning threshold as a fraction of each measure's quantity (low-capacity-warning)"
      },
      "applications": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "id",
            "label",
            "state",
            "state_since",
            "checked_at",
            "measures",
            "egress_limits"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "size": {
              "anyOf": [
                {
                  "$ref": "#/shapes/app_size"
                },
                {
                  "type": "null"
                }
              ]
            },
            "unlimited": {
              "type": "boolean",
              "description": "True on the company's own applications, where `size` is null. Absent on every other application."
            },
            "state": {
              "type": "string",
              "enum": [
                "ok",
                "warning",
                "over",
                "unset",
                "unknown"
              ],
              "description": "the worst recorded measure state as read now; unknown until a state is recorded (ACB-L0-26)"
            },
            "state_since": {
              "type": [
                "string",
                "null"
              ]
            },
            "checked_at": {
              "type": [
                "string",
                "null"
              ],
              "description": "the last check's stamp, the check a deploy runs where none is recorded, or the daily check; null before the first check. A router report can record a state before the first check, when the traffic totals come from this month's router counts."
            },
            "note": {
              "type": "string",
              "description": "Present only where `checked_at` is null. It says the first daily check has not run or gives the time of a failed check. The check runs within a day. Until a check succeeds, traffic totals come from this month's router counts and stored data is not yet sampled (ACB-L0-26)."
            },
            "measures": {
              "type": "object",
              "required": [
                "backend_actions",
                "data_transfer_bytes",
                "stored_data_bytes",
                "ai_allowance_usd_micros",
                "push_messages",
                "email_recipients",
                "function_calls"
              ],
              "properties": {
                "backend_actions": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "One unit per request the serving router forwards to the application's backend, a scheduled run among them, one per data message a client sends on a WebSocket, plus each end-user sign-in and each session verification the accounts service performs. A request the router verifies itself counts once, and the work inside a request is not counted again. The router sends counts once a minute, including WebSocket messages. Requests and messages under two minutes old may not yet count in `month_total`. Sign-ins and verifications reach the measure at the daily check.",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "requests",
                        "file_puts",
                        null
                      ]
                    }
                  }
                },
                "data_transfer_bytes": {
                  "$ref": "#/shapes/usage_measure",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "requests",
                        "file_puts",
                        null
                      ]
                    }
                  }
                },
                "stored_data_bytes": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "Over, it refuses `file_puts`: the file puts on the application's bound storage areas, which the object storage surface refuses by the same name. No usage state refuses the application's calls of the platform upstream issue-tracking at the egress gateway, its writes and its reads alike.",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "requests",
                        "file_puts",
                        null
                      ]
                    }
                  }
                },
                "ai_allowance_usd_micros": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "Read live at the call: `month_total` is the included AI allowance's micro-dollars drawn this UTC month, 1,000,000 to the dollar, from the platform upstream's drawn rows, a passed call's or a forwarded call's ended early. Each row uses its model's rates in effect at the call if the platform prices it. Otherwise it uses the rates then in effect from the row with the highest base output rate (EGW-L0-06). For a size, `quota` is null and `state` never reads `over`. AI draws your account's balance; read `read_balance` for what is drawn and left. It joins no overall state, because a drawn allowance stops allowance calls and nothing else (ACB-L0-53). Where an allowance quantity applies, an over reading refuses `ai_calls`: the egress gateway refuses the application's ai-allowance calls 429 allowance_exhausted (EGW-L0-06).",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "ai_calls",
                        null
                      ]
                    }
                  }
                },
                "push_messages": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "Counted at the send in the application's month row and read at the call: `month_total` is the deliveries the push service accepted for the application this UTC month, one per device a send accepted, every environment counted (PSH-L0-05). The `quota` is the size's served `push-messages-capacity` quantity, a count of accepted deliveries. It joins no overall state, because a spent quantity stops the application's sends and nothing else. Over, it refuses `push_sends`: the push service refuses the application's sends 429 usage_over_quota (PSH-L0-05).",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "push_sends",
                        null
                      ]
                    }
                  }
                },
                "email_recipients": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "Counted at the send in the application's counter rows and read at the call: `month_total` is the recipients the email service's accepted sends addressed this UTC month, `to` and `cc` together, every environment counted (EML-L0-03). The month's `quota` is null for a size. Where a monthly quantity applies, spending it stops only the application's email sends. An over reading refuses `email_sends` as `email_limit_reached`. Beside the base members, `hour` and `day` carry the same count for the current UTC hour and day against `email-recipients-per-hour` and `email-recipients-per-day`, at which the send route also refuses.",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "email_sends",
                        null
                      ]
                    },
                    "hour": {
                      "$ref": "#/shapes/email_period"
                    },
                    "day": {
                      "$ref": "#/shapes/email_period"
                    }
                  }
                },
                "function_calls": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "`month_total` is the application's function calls reported this UTC month, both environments together (ACB-L0-26). `router` is the only key in `includes_before`; `by_environment` splits the routed rows from their first day this month and is null if no routed row has an environment this month. `quota`, `resets_at` and `refuses` are null, and `state` is `unset`: calls are charged at the `function-calls` rate, not refused on a count. A function's request adds no backend action."
                }
              }
            },
            "egress_limits": {
              "type": "object",
              "description": "The application's outbound limits for the current UTC day, served from its size's quantity rows and counted for the whole application. The tunnel proxy refuses a connection past either limit and cuts open connections past the day limit; the gateway refuses calls to the application's own upstreams past it. A limit whose cell is Unset is no bound.",
              "required": [
                "connections_per_minute",
                "bytes_per_day",
                "bytes_today",
                "refused_today",
                "state",
                "resets_at"
              ],
              "properties": {
                "connections_per_minute": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The outbound connections the application may open per UTC minute on one tunnel proxy replica, or null where the size's cell is Unset. Both sizes have the same quantity."
                },
                "bytes_per_day": {
                  "type": [
                    "integer",
                    "null"
                  ],
                  "description": "The bytes the application's outbound connections and its own upstream calls may carry per UTC day, both ways, or null where the size's cell is Unset. Both sizes have the same quantity."
                },
                "bytes_today": {
                  "type": "integer",
                  "description": "The bytes counted so far today, in UTC, for the whole application; the figure lags the wire by the flush intervals the concepts page states."
                },
                "refused_today": {
                  "type": "integer",
                  "description": "The connections and calls refused at either limit so far today, in UTC."
                },
                "state": {
                  "type": "string",
                  "enum": [
                    "ok",
                    "capped",
                    "unset"
                  ],
                  "description": "`ok` under the day limit, `capped` at or past it, `unset` where the day limit's cell is Unset."
                },
                "resets_at": {
                  "type": "string",
                  "description": "The first instant of the next UTC day, when the day's figures reset, in ISO 8601 form."
                }
              }
            },
            "limits": {
              "type": "array",
              "description": "One row per size quantity the measures and egress_limits above do not cover, and per environment where the quantity counts each environment apart (PRC-L0-16). A quantity retired for sizes has no row. A count is null where read_usage reads no count for the application, as for database connections. The deploy count covers the rolling last 24 hours.",
              "items": {
                "type": "object",
                "required": [
                  "quantity",
                  "environment",
                  "limit",
                  "count",
                  "resets_at"
                ],
                "properties": {
                  "quantity": {
                    "type": "string",
                    "enum": [
                      "database-connection-limit",
                      "schedule-minimum-interval",
                      "schedule-count-limit",
                      "deploys-per-day",
                      "log-retained-capacity",
                      "development-halt-after-days",
                      "development-realm-account-limit",
                      "signin-code-sends-per-hour",
                      "websocket-connections-per-replica",
                      "free-socket-hours-per-month"
                    ],
                    "description": "The quantity's entry name in the pricing registry, as read_plan_quotas gives it."
                  },
                  "environment": {
                    "enum": [
                      "development",
                      "production",
                      null
                    ],
                    "description": "The environment the row counts, or null where the quantity is the whole application's."
                  },
                  "limit": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "description": "The size's cell, in the unit read_plan_quotas gives, or null where the cell is Unset; where a cell is unset and a default applies, the quantity's own page gives it."
                  },
                  "count": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0,
                    "description": "The platform's current count in that unit, or null where read_usage reads no count for the application or its read failed."
                  },
                  "resets_at": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The instant the count next resets, in ISO 8601 form, or null where no fixed instant resets it."
                  },
                  "harness_count": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "minimum": 0,
                    "description": "On the log-retained-capacity row alone: the bytes of the harness's entries the environment holds, which the same limit bounds apart from the count of the application's own entries, or null where its read failed."
                  }
                },
                "additionalProperties": false
              }
            },
            "local_runs": {
              "type": "object",
              "required": [
                "environment",
                "egress_request_bytes",
                "storage_get_bytes",
                "database_size_bytes",
                "detail"
              ],
              "properties": {
                "environment": {
                  "const": "development"
                },
                "egress_request_bytes": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Bytes sent through the egress gateway under the development credential this month."
                },
                "storage_get_bytes": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "Bytes read from the development partitions of the application's storage areas this month."
                },
                "database_size_bytes": {
                  "type": "integer",
                  "minimum": 0,
                  "description": "The development database's size at its last sample."
                },
                "detail": {
                  "type": "string",
                  "description": "One sentence giving the three figures."
                }
              },
              "additionalProperties": false,
              "description": "Present on an application with one environment where development's records hold or drew anything this month (PLD-L0-96). The figures count inside the measures above and add no charge (ACB-L0-26)."
            }
          }
        }
      },
      "detail": {
        "type": "string"
      },
      "page": {
        "$ref": "#/shapes/page"
      }
    }
  }
}
```

## 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/)
