---
title: "Get wallet tier status"
method: GET
path: "/tiers/v1/status"
tags: ["Tiers"]
---

# Get wallet tier status

`GET /tiers/v1/status`

## Request

- Base URL: `https://api.run402.com`
- URL: `https://api.run402.com/tiers/v1/status`
- Auth: API key in header `SIGN-IN-WITH-X`

Returns the wallet's current tier, lease expiry, and resource pool usage. Requires wallet auth.

## Headers

- `SIGN-IN-WITH-X` string, required

## Response `200`

Wallet tier status

- object
  - `wallet` string, required: Lowercased wallet address.
  - `tier` 'prototype' | 'hobby' | 'team' | 'null', nullable, required: Current tier, or null if the wallet has never set one.
  - `lease_started_at` string, date-time, nullable, required: ISO-8601 timestamp when the current lease began. Null if no tier.
  - `lease_expires_at` string, date-time, nullable, required: ISO-8601 timestamp when the current lease expires. Null if no tier.
  - `active` boolean, required: True when a tier is set and the lease is perpetual or its effective expiry is in the future. Perpetual effective expiry is null.
  - `organization_lifecycle_state` 'active' | 'past_due' | 'frozen' | 'dormant' | 'purged' | 'null', nullable, required: Lifecycle state of the owning organization. Null only for orphan wallets with no organization row.
  - `lease_perpetual` boolean, nullable, required: Operator escape hatch flag on the owning organization. When true, the organization never advances past 'active' regardless of lease expiry. Null only for orphan wallets.
  - `lease` 'perpetual' | 'leased' | 'null', nullable, required: kygit-handoff D4 — 'perpetual' for a lease-less tier (prototype: one x402 payment, never expires, never scheduler-advanced), 'leased' for hobby/team. Null only when tier is null.
  - `lease_days` integer, nullable, required: kygit-handoff D4 — days remaining on a LEASED tier (ceil, floored at 0), or null for a perpetual tier or no tier.
  - `downgraded_at` string, date-time, nullable, required: kygit-handoff D4 — ISO-8601 timestamp of the organization's most recent lifecycle-ladder downgrade to perpetual prototype (the ladder's terminal transition; nothing is deleted, hobby/team capacity is restored on renewal). Null if the organization has never been downgraded.
  - `pool_usage` object, required: Aggregate usage across all active projects owned by this wallet, PLUS the organization's retained vault bytes.
    - `projects` integer, required: Number of active projects owned by the wallet.
    - `total_api_calls` integer, required: Sum of api_calls across the wallet's active projects.
    - `total_storage_bytes` integer, required: App storage: sum of storage_bytes across the wallet's active projects PLUS vault_source_bytes, folded together for a single at-a-glance figure. The tier limit it is compared against is storage_bytes_limit; vault's OWN limit is the separate source_bytes_limit below (kygit-handoff D4 — two pooled terms, two limits).
    - `total_storage` string, required: total_storage_bytes as a human string, decimal units. Every human string on this surface sits beside its byte count under the same name with _bytes removed.
    - `vault_source_bytes` integer, required: The vault half of total_storage_bytes, broken out — and the figure compared against source_bytes_limit. Counts EVERY vault in the organization, including vaults whose project has been deleted: vault ciphertext is retained permanently (V0 has no purge verb), so its bytes stay pooled.
    - `vault_source` string, required: vault_source_bytes as a human string, decimal units.
    - `api_calls_limit` integer, required: Tier API-call cap. 0 when no tier is set.
    - `storage_bytes_limit` integer, required: Tier app-storage cap in bytes — a round decimal constant (prototype 250000000 / hobby 1000000000 / team 10000000000). 0 when no tier is set.
    - `storage_limit` string, required: storage_bytes_limit as a human string ("250 MB" / "1 GB" / "10 GB"), derived from the tier constant so the number and the label never disagree. "0 B" when no tier is set.
    - `source_bytes_limit` integer, required: kygit-handoff D4 — the org-pooled vault-bytes cap, a SEPARATE limit from storage_bytes_limit (prototype 1000000000 / hobby 10000000000 / team 50000000000 — 1 GB / 10 GB / 50 GB). A vault QUOTA_EXCEEDED refusal with details.resource:"source_bytes" is computed against vault_source_bytes vs this figure. 0 when no tier is set.
    - `source_limit` string, required: source_bytes_limit as a human string ("1 GB" / "10 GB" / "50 GB"). "0 B" when no tier is set.
    - `vault_egress_bytes_used` integer, required: kygit-handoff D4 — bytes read from the org's vaults this calendar month (UTC), counted at read authorization by stored object size. Prototype-only allowance; always 0 on a leased tier (unmetered).
    - `vault_egress_bytes_limit` integer, nullable, required: kygit-handoff D4 — max(3 GiB, 3 x vault_source_bytes) on prototype; null on hobby/team (leased tiers are unmetered by this allowance in this change). Over it, object reads refuse 403 QUOTA_EXCEEDED with details.resource:"vault_egress_bytes".
  - `projects` WalletTierProject[], required: Non-terminal projects owned by the wallet, with lifecycle and pin state.
    - `name` string, required
    - `created_at` string, date-time, required
    - `secrets_rotation_advised` object: Present after a project ownership transfer (v1.59) until every previously-inherited secret has been re-written by the new owner.
      - `advised_at` string, date-time, required
      - `reason` string, required
    - `project_id` string, required: Run402 project ID. Public IDs are not UUIDs.
  - `advisories` object[]: recovery-event-reachability: org-level advisories. Present only when at least one applies. `owner_unreachable` means the owning organization resolves to zero verified notification recipients, so mandatory recovery/security notifications currently have no human to reach.
    - `type` 'owner_unreachable', required
    - `summary` string, required
    - `next_actions` object[], required
      - `type` string
      - `method` string
      - `path` string
      - `why` string
  - `platform_status` 'degraded': Health-assessment rider. Present and equal to `degraded` only while an open platform incident is global or affects one of this caller's projects; omitted when clear. Read the project events feed (`platform_incident` entries + the `platform_incidents[]` overlay) for the incident detail. The same rider appears on GET /agent/v1/me/status and the events-feed envelope, and nowhere else.

## Other responses

- `401`: Missing or invalid authentication. Run402-originated JSON bodies use the canonical ErrorEnvelope.

---

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