read_usage

{
  "name": "read_usage",
  "resource": "application",
  "tier": "observe",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "summary": "The application's usage against its plan's included measures for the UTC calendar month — backend actions, data transfer, stored data — each with the month's figure to compare (`month_total`) against the plan's served quantity (`quota`), that figure's two parts, the daily check's figure (`used`) and the month's router count beyond that check (`live`), its state (`ok`, `warning` from 80% of the quantity, `over`, `unset`, or `unknown`), the instant an over traffic measure's refusal ends (`resets_at`), and what an over state refuses (`refuses`). Backend actions count one per request the serving router forwards to the application's backend, a scheduled run among them, 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 `live` within about a minute, and sign-ins and verifications reach the measure at the daily check. The `month_total` member is `used` plus `live` where the check ran in the answered month, `live` alone where it ran in an earlier one or has not run, and `used` where `live` is null, so a reader adds nothing. 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, the stored-data state at the daily check; an over state refuses by name — the serving router answers 429 `usage_over_quota` on every application leg of its hostnames until the next UTC month's first instant, the object storage surface refuses file puts on bound areas until the next successful daily pass, a larger plan, or a raised quota — while deploys and every management action continue; with no application named, every live application of the account. The AI allowance and the push messages are counted at each call or send, each state computed at the read and joining no overall state, and a spent quantity refuses those calls or sends until the next UTC month's first instant. `refuses` names `requests`, `file_puts`, `ai_calls`, or `push_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
  }
}

{
  "name": "read_usage",
  "tier": "observe",
  "scenario": "CHI-L0-09",
  "summary": "Read application usage against plan quantities for the current UTC month. Compare each measure's `month_total`, the month's figure, with its `quota`, and add nothing to it. Its two parts stand beside it: `used`, from the last daily check (inspect `checked_at`), and `live`, the month's router count beyond that check. The `month_total` member is `used` plus `live` where that check ran in this month, `live` alone where it ran in an earlier month or has not run, and `used` where `live` is null. The `quota` member reflects currently served plan quantities.\n\nBackend actions count one per request the serving router forwards to the application's backend, a scheduled run among them, 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 `live` within about a minute, and sign-ins and verifications reach the measure at the daily check.\n\nAn application's `state`, the worst of its measures', reads `unknown` until a state is recorded, even where 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 one of the three has no state recorded yet, it reads `unknown` where `month_total` is null, else `unset` where quota is null, `ok` below 80% of quota, and `unknown` otherwise. An `over` state refuses by name. For backend actions and data transfer the serving router answers 429 `usage_over_quota` on every application request and scheduled run until `resets_at`, the next UTC month's first instant.\n\nThe `refuses` member names what is refused (`requests`, `file_puts`, `ai_calls`, or `push_sends`) or is null. Deploys and every management action continue. Stored data has no `live` value. The rest is on the page /cloud/reference/actions/read-usage/, which `read_documentation` reads as `page` and the platform's origin serves.",
  "owners": [
    "ACB-L0-26"
  ]
}

{
  "request": {
    "type": "object",
    "properties": {
      "application": {
        "type": "string",
        "description": "One application id; omitted, every live application of the account."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "period",
      "warning_fraction",
      "applications"
    ],
    "properties": {
      "contract_version": {
        "const": 1
      },
      "reference": {
        "type": "string",
        "pattern": "^[0-9a-f]{10}$",
        "description": "The short reference the platform recorded this call under, ten lowercase hexadecimal characters, the value the call’s record row carries; quote it when reporting the call."
      },
      "period": {
        "type": "string",
        "pattern": "^[0-9]{4}-[0-9]{2}$",
        "description": "the UTC calendar month the counts belong to, YYYY-MM"
      },
      "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",
            "plan",
            "state",
            "state_since",
            "checked_at",
            "measures",
            "egress_limits"
          ],
          "properties": {
            "id": {
              "type": "string"
            },
            "label": {
              "type": "string"
            },
            "plan": {
              "type": "string",
              "enum": [
                "free",
                "standard",
                "pro",
                "unlimited"
              ],
              "description": "`unlimited` is the company's own plan, which no customer act selects yet."
            },
            "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 daily check's stamp; null before the first check. A state may be recorded before the first check, from a router report's recomputation; used is then null and live carries the month's figure"
            },
            "note": {
              "type": "string",
              "description": "Present only where `checked_at` is null. It is one sentence: the daily check has not run for this application yet, or failed at the instant it names. Either way it runs within a day, `backend_actions`, `data_transfer_bytes`, and `stored_data_bytes` answer `used` null until then, and `live` is the month's whole count (ACB-L0-26)."
            },
            "measures": {
              "type": "object",
              "required": [
                "backend_actions",
                "data_transfer_bytes",
                "stored_data_bytes",
                "ai_allowance_units",
                "push_messages"
              ],
              "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, 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's count reaches `live` within about a minute; 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. The same name refuses the write calls of the platform upstream issue-tracking at the egress gateway, while its reads continue.",
                  "properties": {
                    "refuses": {
                      "enum": [
                        "requests",
                        "file_puts",
                        null
                      ]
                    }
                  }
                },
                "ai_allowance_units": {
                  "$ref": "#/shapes/usage_measure",
                  "description": "Read live at the call: `used` is the included AI allowance's units drawn this UTC month, from the platform upstream's drawn rows, a passed call's or a forwarded call's ended early (one unit per input token, five per output or thinking token; EGW-L0-06). The `quota` is the plan's served `gemini-flash-allowance` quantity in token units. It joins no overall state, because a drawn allowance stops allowance calls and nothing else (ACB-L0-53). Over, it refuses `ai_calls`: the egress gateway refuses the application's ai-allowance calls 429 allowance_exhausted (EGW-L0-06).",
                  "properties": {
                    "live": {
                      "type": "null"
                    },
                    "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: `used` 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 plan'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": {
                    "live": {
                      "type": "null"
                    },
                    "refuses": {
                      "enum": [
                        "push_sends",
                        null
                      ]
                    }
                  }
                }
              }
            },
            "egress_limits": {
              "type": "object",
              "description": "The application's outbound limits for the current UTC day, served from its plan's quota table 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 plan's cell is Unset."
                },
                "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 plan's cell is Unset."
                },
                "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."
                }
              }
            },
            "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 naming 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"
      }
    }
  }
}