Account

Base URL https://app.mandala.computer/api/v1. Every request carries an API key, and failures take the shape under Errors.

GET`/account`

Read account quotaviewer+

Read the effective plan, account pool ceilings, per-computer maxima and current consumption before choosing a create or resize. Viewer or stronger; workspace-scoped keys receive whole-account aggregates without resource, workspace, member or billing identities. An authorized holder may read a suspended account to understand its quota. Suspended holders and revoked credentials remain refused.

READ complete BEFORE USING NUMBERS. An incomplete computer or snapshot collection returns 200 with every usage and remaining field for that group null. The other group and verified caps remain usable. Complete empty inventories are real zero; zero ceilings on a no-plan account do not erase retained usage. Overages remain visible in usage even though remaining is clamped to zero.

Snapshot headroom is against indexed stored bytes, including pending/deleting entries and each physical copy during handover. Capture placeholders have zero indexed bytes; private in-flight capture reservations are not exposed. This is not an available reservation for a new capture.

Advisory and uncached: concurrent changes can make the observation stale immediately, and observed_at is no consistency token. Creates count the effective template or snapshot disk floor. Resizes replace configured CPU/disk and allow reductions or unchanged overages after downgrade. A stopped resize consumes no running RAM; later start checks active or reserved count, CPU and RAM separately. Host fit and move consent remain separate. Existing mutation admission and 402 messages are unchanged. This read never stops, starts or resizes a computer.

Admission counts two things this read leaves out: creates and clones whose outcome was never heard, and the reservations held for seeds your own templates boot. See advisory on the response.

Set MANDALA_API_KEY to your bearer key. MANDALA_BASE_URL, when set, is the full API base including /api/v1. Replace the illustrative resource IDs with yours. These pinned 0.16.0 SDK and direct HTTP examples do not read saved device-login credentials.

curl

base_url="${MANDALA_BASE_URL:-}"
if [ -z "$base_url" ]; then base_url='https://app.mandala.computer/api/v1'; fi
curl --fail-with-body "${base_url%/}"'/account' \
  -H "Authorization: Bearer $MANDALA_API_KEY"

Python — Mandala SDK 0.16.0

# Python 3.10+: pip install mandala-computer==0.16.0
import os
from mandala_computer import Client

with Client(api_key=os.environ["MANDALA_API_KEY"], base_url=os.environ.get("MANDALA_BASE_URL") or "https://app.mandala.computer/api/v1") as client:
    result = client.account.read()
    print(result)

TypeScript — Mandala SDK 0.16.0

// Node.js 22+: npm install mandala-computer@0.16.0
import { Client } from "mandala-computer";

const apiKey = process.env.MANDALA_API_KEY;
if (!apiKey) throw new Error("Set MANDALA_API_KEY");
const client = new Client({apiKey, baseUrl: process.env.MANDALA_BASE_URL || "https://app.mandala.computer/api/v1"});
const result = await client.account.read();
console.log(JSON.stringify(result, null, 2));

200 Illustrative successful response.

HTTP 200
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17

{
  "scope": "account",
  "advisory": true,
  "observed_at": "2026-09-16T12:00:00.000Z",
  "plan": {
    "id": "solo",
    "label": "Solo"
  },
  "limits": {
    "max_computers": 4,
    "vcpu_pool": 4,
    "ram_pool_mb": 8192,
    "disk_pool_gb": 80,
    "snapshot_storage_bytes": 171798691840
  },
  "per_computer": {
    "max_vcpu": 4,
    "max_ram_mb": 8192,
    "max_disk_gb": 40
  },
  "capabilities": {
    "windows": false
  },
  "complete": {
    "computers": true,
    "snapshots": true
  },
  "usage": {
    "kept_computers": 1,
    "configured_vcpu": 2,
    "configured_disk_gb": 20,
    "running_or_reserved_computers": 1,
    "running_or_reserved_vcpu": 2,
    "running_or_reserved_ram_mb": 2048,
    "snapshot_storage_bytes": 0
  },
  "remaining": {
    "kept_computers": 3,
    "configured_vcpu": 2,
    "configured_disk_gb": 60,
    "running_or_reserved_ram_mb": 6144,
    "snapshot_storage_bytes": 171798691840
  }
}

200 Successful quota observation with unavailable computer totals.

HTTP 200
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17

{
  "scope": "account",
  "advisory": true,
  "observed_at": "2026-09-16T12:00:00.000Z",
  "plan": {
    "id": "solo",
    "label": "Solo"
  },
  "limits": {
    "max_computers": 4,
    "vcpu_pool": 4,
    "ram_pool_mb": 8192,
    "disk_pool_gb": 80,
    "snapshot_storage_bytes": 171798691840
  },
  "per_computer": {
    "max_vcpu": 4,
    "max_ram_mb": 8192,
    "max_disk_gb": 40
  },
  "capabilities": {
    "windows": false
  },
  "complete": {
    "computers": false,
    "snapshots": true
  },
  "usage": {
    "kept_computers": null,
    "configured_vcpu": null,
    "configured_disk_gb": null,
    "running_or_reserved_computers": null,
    "running_or_reserved_vcpu": null,
    "running_or_reserved_ram_mb": null,
    "snapshot_storage_bytes": 0
  },
  "remaining": {
    "kept_computers": null,
    "configured_vcpu": null,
    "configured_disk_gb": null,
    "running_or_reserved_ram_mb": null,
    "snapshot_storage_bytes": 171798691840
  }
}

401 Platform bearer credential missing.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer

{
  "error": "Authentication required",
  "reason": "missing",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

401 Platform bearer credential invalid.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer error="invalid_token"

{
  "error": "invalid API key",
  "reason": "invalid",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

401 Platform bearer credential revoked.

HTTP 401
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
WWW-Authenticate: Bearer error="invalid_token"

{
  "error": "API key revoked",
  "reason": "revoked",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

405 Unsupported method on this public path; HEAD returns these headers without a body.

HTTP 405
Content-Type: application/json
X-Request-ID: 3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17
Allow: GET, HEAD, OPTIONS

{
  "error": "method not allowed",
  "request_id": "3f2c9a1e-7b4d-4e8a-9c61-0d5f2b8e4a17"
}

Response

Verified plan ceilings and independently complete or unknown quota totals.

Response fields

`scope`always	string	Whole-account aggregates, including for workspace-scoped viewers.
`advisory`always	boolean	An observation, never an admission guarantee or reservation. Admission — of a create or clone, a start, restart, restore or resume, a resize, a move, a never-suspend pin or a template build — also counts two things left out here: a create or clone that reached a host whose answer was lost, or was a `5xx` that cannot rule out a computer was built (see `POST /computers`), and a reservation of running vCPU and RAM for each seed one of your own templates boots for fast launches. The seed has 30 seconds to start, but its reservation stays charged until the platform confirms both that the seed is gone and that its permission to start has run out. While its host cannot be asked — unreachable, halted, removed or registered again — it stays charged. Either can make a `402` name more than these numbers show.
`observed_at`always	string	UTC collection completion time; not a consistency token.
`plan`always	object
`limits`always	object
`per_computer`always	object
`capabilities`always	object
`complete`always	object
`usage`always	object
`remaining`always	object

Failures

403

A suspended account may still make this read: a 403 here is about the credential or the person holding it, never the account’s suspension.

GET/account