GET/api/orgs/{org_id}/identities/{identity_id}/allowances

Get an identity's plan allowances

Any key may read its own identity (another identity answers 404). A provisioning key (not plan-bound) may read any identity in its organization. Counters are the ones admission enforces, at frozen list value, integer nano-USD (with exact decimal strings).

Authentication: Bearer API key in the Authorization header

Path parameters

  • org_idstringrequired

    Your organization id (uuid). GET /api/whoami returns it.

  • identity_idstringrequired

    Identity id.

Responses

  • 200

    Allowances.

    Response
    • identity_idstringrequired
    • assignmentobject | nullrequired
      One of

      object

      • org_idstringrequired
      • identity_idstringrequired
      • revisionintegerrequired

        Pass as expected_revision on the next PUT.

      • plan_keystring | nullrequired
      • plan_versioninteger | nullrequired
      • pending_plan_keystring | nullrequired
      • pending_plan_versioninteger | nullrequired
      • pending_effective_atstring | nullrequired
      • updated_atstringrequired
      • budget_periodobject
        One of

        object

        • kindstringrequired

        object

        • kindstringrequired
        • source_period_idstringrequired
        • startstringrequired
        • endstringrequired
    • pricing_basisstringrequired
    • period_startstringrequired
    • period_endstringrequired
    • groupsarray<object>required
      groups
      • group_keystringrequired
      • limit_nano_usdintegerrequired

        Integer nano-USD.

      • settled_nano_usdintegerrequired

        Integer nano-USD.

      • reserved_nano_usdintegerrequired

        In flight, integer nano-USD.

      • pending_nano_usdintegerrequired

        Integer nano-USD.

      • remaining_nano_usdintegerrequired

        Integer nano-USD.

      • exactobjectrequired

        The same counters as decimal strings, for clients whose JSON numbers are floats.

        exact
        • settled_nano_usdstringrequired
        • reserved_nano_usdstringrequired
        • pending_nano_usdstringrequired
        • remaining_nano_usdstring | nullrequired
    • budget_periodobject
      One of

      object

      • kindstringrequired

      object

      • kindstringrequired
      • source_period_idstringrequired
      • startstringrequired
      • endstringrequired
    • aggregateobject | null
      One of

      object

      • limit_nano_usdinteger | nullrequired
      • settled_nano_usdintegerrequired

        Integer nano-USD.

      • reserved_nano_usdintegerrequired

        In flight, integer nano-USD.

      • pending_nano_usdintegerrequired

        Integer nano-USD.

      • remaining_nano_usdinteger | nullrequired
      • exactobjectrequired

        The same counters as decimal strings, for clients whose JSON numbers are floats.

        exact
        • settled_nano_usdstringrequired
        • reserved_nano_usdstringrequired
        • pending_nano_usdstringrequired
        • remaining_nano_usdstring | nullrequired
  • 401

    Missing, unknown or revoked API key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 403

    Not authorized for this policy change, or a customer-plan key.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 404

    Unknown organization, identity or plan.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

  • 409

    Stale expected_revision, or customer-plan enforcement is off on this deployment.

    Response
    • errorstringrequired

      Human-readable message.

    • codestring

      Stable machine reason, when the route defines one (for example pro_required).

    • actionstring

      Stable remediation action, when the route defines one.

    • detailsobject

      Customer-safe string facts the caller needs to act (for example a suggested identifier).

Request

curl https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/identities/acme-support/allowances \
  -H "Authorization: Bearer YOUR_API_KEY"

Response

{
  "identity_id": "acme-support",
  "assignment": {
    "org_id": "3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10",
    "identity_id": "acme-support",
    "revision": 3,
    "plan_key": "starter",
    "plan_version": 2,
    "pending_plan_key": null,
    "pending_plan_version": null,
    "pending_effective_at": null,
    "updated_at": "2026-11-10T16:00:00Z",
    "budget_period": {
      "kind": "calendar_month_utc"
    }
  },
  "pricing_basis": "frozen_list_value",
  "period_start": "2026-11-01T00:00:00Z",
  "period_end": "2026-12-01T00:00:00Z",
  "groups": [
    {
      "group_key": "fast-models",
      "limit_nano_usd": 20000000000,
      "settled_nano_usd": 6400000000,
      "reserved_nano_usd": 40000000,
      "pending_nano_usd": 0,
      "remaining_nano_usd": 13560000000,
      "exact": {
        "settled_nano_usd": "6400000000",
        "reserved_nano_usd": "40000000",
        "pending_nano_usd": "0",
        "remaining_nano_usd": "13560000000"
      }
    }
  ],
  "budget_period": {
    "kind": "calendar_month_utc"
  },
  "aggregate": null
}

https://api.experientiallabs.ai/api/orgs/3f6c2a1e-8b7d-4c2a-9e51-6a0d4b2f7c10/identities/acme-support/allowances