read_platform_usage

Generated automatically from the published contract sources.

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.

A script calls this action over HTTPS at POST https://turnzero.ai/api/v1/actions/read_platform_usage, with a bearer credential and the action's payload as the JSON body. It also accepts GET.

Contract description

Read every live application's plan, usage, and issue-tracking reading across every account. Super-admin (platform operator) only. The reading covers this month's gateway calls and each space's last stored bytes, and nothing refuses on it. It also reads the quota rows the operator has set with their stamps and authors, and — with `cost` true — the hosting subscription's month-to-date cost per resource from its cost service.

Access and action metadata

{
  "name": "read_platform_usage",
  "resource": "account",
  "tier": "observe",
  "clients": [
    "bearer",
    "browser_session"
  ],
  "grant": "super_admin",
  "summary": "Super-admin: every live application's plan, usage snapshot, and issue-tracking reading across every account, the reading this month's gateway calls and each space's last stored bytes, which nothing refuses on; the served quota rows with their stamps and authors; and — with `cost` true — the hosting subscription's month-to-date cost per resource from its cost service, `azure_detail` naming an absent or failed read.",
  "annotations": {
    "readOnlyHint": true,
    "destructiveHint": false,
    "openWorldHint": true,
    "idempotentHint": true
  }
}

MCP catalog entry

{
  "name": "read_platform_usage",
  "tier": "observe",
  "scenario": "API-L0-12",
  "summary": "Read every live application's plan, usage, and issue-tracking reading across every account. Super-admin (platform operator) only. The reading covers this month's gateway calls and each space's last stored bytes, and nothing refuses on it. It also reads the quota rows the operator has set with their stamps and authors, and — with `cost` true — the hosting subscription's month-to-date cost per resource from its cost service.",
  "owners": [
    "ACB-L0-79",
    "API-L0-12"
  ]
}

request

JSON pointer	Description and constraints
"" (root)	Type: object
/properties/cost	`true` to include the month-to-date cost from the hosting subscription's cost service; `false` (the default) makes no call to it. Type: boolean

response

JSON pointer	Description and constraints
"" (root)	Type: object Required fields: ["contract_version","period","quotas","applications","azure"]
/properties/contract_version	Required value: 1
/properties/reference	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. Type: string Pattern: ^[0-9a-f]{10}$
/properties/period	Type: string Pattern: ^[0-9]{4}-[0-9]{2}$
/properties/quotas	the served quota rows with their stamps and authors, per plan the ten enforced entries and then the served values the plan sets (PRC-L0-16). The retired entry `issue-tracking-calls` is not answered. Type: array
/properties/quotas/items	Type: object Required fields: ["plan","measure","quantity","set_at","set_by"]
/properties/quotas/items/properties/plan	The row's plan: `free`, `standard`, or `pro`, or `unlimited`, the company's own plan, which no customer act selects yet. Type: string Allowed values: ["free","standard","pro","unlimited"]
/properties/quotas/items/properties/measure	Type: string Allowed values: ["stored-data-capacity","backend-actions-capacity","data-transfer-capacity","database-connection-limit","schedule-minimum-interval","schedule-count-limit","deploys-per-day","log-retained-capacity","gemini-flash-allowance","free-idle-stop","development-halt-after-days","development-realm-account-limit","signin-code-sends-per-hour","egress-connections-per-minute","egress-bytes-per-day","push-messages-capacity"]
/properties/quotas/items/properties/quantity	Type: ["integer","null"]
/properties/quotas/items/properties/set_at	Type: string
/properties/quotas/items/properties/set_by	Type: string
/properties/applications	Type: array
/properties/applications/items	every live application across every account: id, account, label, plan, the container app name where placed, `synthetic` (the owning account's flag, true for a test fixture seed_synthetic_accounts created; ACB-L0-79), and the usage snapshot as read_usage answers it, the `ai_allowance_units` measure included. Its plan is `free`, `standard`, `pro`, or `unlimited`, the company's own plan, which no customer act selects yet. Each also carries `issue_tracking`, its issue-tracking reading (ITS-L0-04; ACB-L0-79): `calls`, the calls the egress gateway forwarded to its spaces this UTC month, for the whole application (PLD-L0-96). Its `spaces` lists each space the application reaches. Each entry carries `space`, the space's identifier, and `kind`, `application` for the application's own space or one of its per-environment pair, or `account` for a space of the account's own its manifest binds. It carries `environment`, the environment the space serves, or null for a space serving both, and `bytes`, the stored bytes at the daily pass's last answered read, or null where none named the space. Its `bytes_read_at` is that read's stamp, or null before one. No plan bounds the reading and nothing refuses on it Type: object
/properties/azure	the month-to-date cost per resource — as_of, currency, rows of resource_id, resource_group, cost — or null where cost was not requested, the credential is absent, or the read failed Type: ["object","null"]
/properties/azure_detail	why azure is null: cost not requested, the cost service credential absent, or the cost read failed Type: string
/properties/detail	Type: string
/properties/page	$ref: #/shapes/page
/properties/synthetic	The synthetic estate's standing (ACB-L0-79): optional, never required, absent where the plane cannot read the estate. Type: object Required fields: ["posture","standing_accounts","standing_applications","paid_applications","oldest_seeded_at","seeded_today","ceilings"]
/properties/synthetic/properties/posture	The control plane's `SYNTHETIC_ESTATE` mode as the plane reads it, `on` read as `compat` and an unparseable value as `off` (MAPI-16). Type: string Allowed values: ["off","compat","stress"]
/properties/synthetic/properties/expires_on	The `stress` mode's expiry date from the setting's value; null under every other mode. Type: ["string","null"]
/properties/synthetic/properties/standing_accounts	Type: integer Minimum: 0
/properties/synthetic/properties/standing_applications	Type: integer Minimum: 0
/properties/synthetic/properties/paid_applications	The standing synthetic applications on a paid plan. Type: integer Minimum: 0
/properties/synthetic/properties/oldest_seeded_at	The seeding instant of the oldest standing synthetic account; null where none stands. Type: ["string","null"]
/properties/synthetic/properties/seeded_today	The accounts seeded by this operator's account in the current UTC day. Type: integer Minimum: 0
/properties/synthetic/properties/ceilings	The mode's ceilings as MAPI-16 states them, each an integer. Type: object Required fields: ["standing_accounts","standing_applications","paid_applications","accounts_per_seed","token_expiry_days","lifetime_days","seeded_per_day"]
/properties/synthetic/properties/ceilings/properties/standing_accounts	Type: integer
/properties/synthetic/properties/ceilings/properties/standing_applications	Type: integer
/properties/synthetic/properties/ceilings/properties/paid_applications	Type: integer
/properties/synthetic/properties/ceilings/properties/accounts_per_seed	Type: integer
/properties/synthetic/properties/ceilings/properties/token_expiry_days	Type: integer
/properties/synthetic/properties/ceilings/properties/lifetime_days	Type: integer
/properties/synthetic/properties/ceilings/properties/seeded_per_day	Type: integer

Complete payload contract

{
  "request": {
    "type": "object",
    "properties": {
      "cost": {
        "type": "boolean",
        "description": "`true` to include the month-to-date cost from the hosting subscription's cost service; `false` (the default) makes no call to it."
      }
    }
  },
  "response": {
    "type": "object",
    "required": [
      "contract_version",
      "period",
      "quotas",
      "applications",
      "azure"
    ],
    "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}$"
      },
      "quotas": {
        "type": "array",
        "items": {
          "type": "object",
          "required": [
            "plan",
            "measure",
            "quantity",
            "set_at",
            "set_by"
          ],
          "properties": {
            "plan": {
              "type": "string",
              "enum": [
                "free",
                "standard",
                "pro",
                "unlimited"
              ],
              "description": "The row's plan: `free`, `standard`, or `pro`, or `unlimited`, the company's own plan, which no customer act selects yet."
            },
            "measure": {
              "type": "string",
              "enum": [
                "stored-data-capacity",
                "backend-actions-capacity",
                "data-transfer-capacity",
                "database-connection-limit",
                "schedule-minimum-interval",
                "schedule-count-limit",
                "deploys-per-day",
                "log-retained-capacity",
                "gemini-flash-allowance",
                "free-idle-stop",
                "development-halt-after-days",
                "development-realm-account-limit",
                "signin-code-sends-per-hour",
                "egress-connections-per-minute",
                "egress-bytes-per-day",
                "push-messages-capacity"
              ]
            },
            "quantity": {
              "type": [
                "integer",
                "null"
              ]
            },
            "set_at": {
              "type": "string"
            },
            "set_by": {
              "type": "string"
            }
          }
        },
        "description": "the served quota rows with their stamps and authors, per plan the ten enforced entries and then the served values the plan sets (PRC-L0-16). The retired entry `issue-tracking-calls` is not answered."
      },
      "applications": {
        "type": "array",
        "items": {
          "type": "object",
          "description": "every live application across every account: id, account, label, plan, the container app name where placed, `synthetic` (the owning account's flag, true for a test fixture seed_synthetic_accounts created; ACB-L0-79), and the usage snapshot as read_usage answers it, the `ai_allowance_units` measure included. Its plan is `free`, `standard`, `pro`, or `unlimited`, the company's own plan, which no customer act selects yet. Each also carries `issue_tracking`, its issue-tracking reading (ITS-L0-04; ACB-L0-79): `calls`, the calls the egress gateway forwarded to its spaces this UTC month, for the whole application (PLD-L0-96). Its `spaces` lists each space the application reaches. Each entry carries `space`, the space's identifier, and `kind`, `application` for the application's own space or one of its per-environment pair, or `account` for a space of the account's own its manifest binds. It carries `environment`, the environment the space serves, or null for a space serving both, and `bytes`, the stored bytes at the daily pass's last answered read, or null where none named the space. Its `bytes_read_at` is that read's stamp, or null before one. No plan bounds the reading and nothing refuses on it"
        }
      },
      "azure": {
        "type": [
          "object",
          "null"
        ],
        "description": "the month-to-date cost per resource — as_of, currency, rows of resource_id, resource_group, cost — or null where cost was not requested, the credential is absent, or the read failed"
      },
      "azure_detail": {
        "type": "string",
        "description": "why azure is null: cost not requested, the cost service credential absent, or the cost read failed"
      },
      "detail": {
        "type": "string"
      },
      "page": {
        "$ref": "#/shapes/page"
      },
      "synthetic": {
        "type": "object",
        "description": "The synthetic estate's standing (ACB-L0-79): optional, never required, absent where the plane cannot read the estate.",
        "required": [
          "posture",
          "standing_accounts",
          "standing_applications",
          "paid_applications",
          "oldest_seeded_at",
          "seeded_today",
          "ceilings"
        ],
        "properties": {
          "posture": {
            "type": "string",
            "enum": [
              "off",
              "compat",
              "stress"
            ],
            "description": "The control plane's `SYNTHETIC_ESTATE` mode as the plane reads it, `on` read as `compat` and an unparseable value as `off` (MAPI-16)."
          },
          "expires_on": {
            "type": [
              "string",
              "null"
            ],
            "description": "The `stress` mode's expiry date from the setting's value; null under every other mode."
          },
          "standing_accounts": {
            "type": "integer",
            "minimum": 0
          },
          "standing_applications": {
            "type": "integer",
            "minimum": 0
          },
          "paid_applications": {
            "type": "integer",
            "minimum": 0,
            "description": "The standing synthetic applications on a paid plan."
          },
          "oldest_seeded_at": {
            "type": [
              "string",
              "null"
            ],
            "description": "The seeding instant of the oldest standing synthetic account; null where none stands."
          },
          "seeded_today": {
            "type": "integer",
            "minimum": 0,
            "description": "The accounts seeded by this operator's account in the current UTC day."
          },
          "ceilings": {
            "type": "object",
            "description": "The mode's ceilings as MAPI-16 states them, each an integer.",
            "required": [
              "standing_accounts",
              "standing_applications",
              "paid_applications",
              "accounts_per_seed",
              "token_expiry_days",
              "lifetime_days",
              "seeded_per_day"
            ],
            "properties": {
              "standing_accounts": {
                "type": "integer"
              },
              "standing_applications": {
                "type": "integer"
              },
              "paid_applications": {
                "type": "integer"
              },
              "accounts_per_seed": {
                "type": "integer"
              },
              "token_expiry_days": {
                "type": "integer"
              },
              "lifetime_days": {
                "type": "integer"
              },
              "seeded_per_day": {
                "type": "integer"
              }
            }
          }
        }
      }
    }
  }
}

Shared contracts

Refusals: every refusal, by surface, with its cause and its remedy
schemas/wire_error.schema.json
schemas/wire_errors.json
schemas/action_payloads.json (includes shared shapes)
management_api_contract.md