---
title: "Plan, usage and limits"
description: "Retrieve the organisation's plan, usage, and allowed features."
canonical: "https://grid82.com/docs/builder-api/billing/get"
updated: "2026-11-13"
---

# Plan, usage and limits

`GET https://studio.grid82.app/v1/organizations/{organizationId}/billing`

Retrieve the organisation's plan, usage, and allowed features.

`plan` is the id: `free` is the plan named Solo. Limits are counted against the organisation that pays; suites are never billed for existing.

Requires the `account:read` scope. Operation `billing.get`. MCP tool `billing_get`. CLI: `grid82 billing get` (`npx grid82`).

## Path parameters

| Name             | Type   | Required | Description |
| ---------------- | ------ | -------- | ----------- |
| `organizationId` | string | yes      |             |

**Authorizations**

- `Authorization` (bearer, in header, required)

## Response

**200**: Success

- `data` (`object`, required)
- `data.organizationId` (`string`, required)
- `data.plan` (`enum<string>`, required, one of: `free, starter, pro, custom`)
- `data.planStatus` (`string`, required)
- `data.renewsAt` (`string,null`, required)
- `data.hasPaymentMethod` (`boolean`, required)
- `data.usage` (`object`, required)
- `data.usage.suites` (`integer`, required)
- `data.usage.apps` (`integer`, required)
- `data.usage.users` (`integer`, required)
- `data.usage.builders` (`integer`, required)
- `data.usage.storageBytes` (`integer`)
- `data.usage.customDomains` (`integer`)
- `data.limits` (`object`, required)
- `data.limits.builders` (`integer | null`, required)
- `data.limits.suites` (`integer | null`, required)
- `data.limits.apps` (`integer | null`, required)
- `data.limits.users` (`integer | null`, required)
- `data.limits.rowsPerApp` (`integer | null`, required)
- `data.limits.storageBytes` (`integer | null`, required)
- `data.limits.customDomains` (`integer | null`, required)
- `data.limits.assistantCredits` (`integer | null`, required)
- `data.addons` (`Record<string, integer>`, required)
- `data.subscription` (`object`, required)
- `data.subscription.live` (`boolean`, required)
- `data.subscription.interval` (`enum<string> | null`, required)
- `data.subscription.cancelAt` (`string,null`, required)
- `data.subscription.pendingChange` (`object | null`, required)
- `data.subscription.pendingChange.plan` (`enum<string>`, required, one of: `free, starter, pro, custom`)
- `data.subscription.pendingChange.interval` (`enum<string> | null`, required)
- `data.subscription.pendingChange.effectiveAt` (`string,null`, required)
- `data.checkout` (`object`, required)
- `data.checkout.connected` (`boolean`, required)
- `data.checkout.reason` (`string,null`, required)
- `data.checkout.purchasable` (`object[]`, required)
- `data.checkout.purchasable.plan` (`enum<string>`, required, one of: `free, starter, pro, custom`)
- `data.checkout.purchasable.interval` (`enum<string>`, required, one of: `monthly, yearly`)
- `data.grants` (`object`, required)
- `data.grants.availableCredits` (`number`, required)
- `data.grants.pendingCredits` (`number`, required)
- `data.pricingIsPlaceholder` (`boolean`, required)

```json
{
  "data": {
    "organizationId": "<string>",
    "plan": "free",
    "planStatus": "<string>",
    "renewsAt": null,
    "hasPaymentMethod": true,
    "usage": {
      "suites": 123,
      "apps": 123,
      "users": 123,
      "builders": 123,
      "storageBytes": 123,
      "customDomains": 123
    },
    "limits": {
      "builders": 123,
      "suites": 123,
      "apps": 123,
      "users": 123,
      "rowsPerApp": 123,
      "storageBytes": 123,
      "customDomains": 123,
      "assistantCredits": 123
    },
    "addons": {},
    "subscription": {
      "live": true,
      "interval": "monthly",
      "cancelAt": null,
      "pendingChange": {
        "plan": "free",
        "interval": "monthly",
        "effectiveAt": null
      }
    },
    "checkout": {
      "connected": true,
      "reason": null,
      "purchasable": [
        {
          "plan": "free",
          "interval": "monthly"
        }
      ]
    },
    "grants": {
      "availableCredits": 123.45,
      "pendingCredits": 123.45
    },
    "pricingIsPlaceholder": true
  }
}
```

**4XX**: Refused

- `error` (`object`, required)
- `error.code` (`enum<string>`, required, one of: `not_found, forbidden, unauthenticated, validation_failed, conflict, rate_limited, payment_required, not_implemented, internal`)
- `error.message` (`string`, required)
- `error.details` (`Record<string, unknown>`)

```json
{
  "error": {
    "code": "not_found",
    "message": "<string>",
    "details": {}
  }
}
```

**Example request**

```bash
curl --request GET \
  --url 'https://studio.grid82.app/v1/organizations/<organizationId>/billing' \
  --header 'Authorization: Bearer <token>'
```