---
title: "Return the caller's account: identity, plan, entitlements, cost ceilings"
method: GET
path: "/v1/me"
tags: ["account"]
---

# Return the caller's account: identity, plan, entitlements, cost ceilings

`GET /v1/me`

## Request

- Base URL: `https://api.cueframe.ai`
- URL: `https://api.cueframe.ai/v1/me`
- Auth: one of:
  - HTTP bearer
  - OAuth 2 (authorization code, authorization URL `https://api.cueframe.ai/api/auth/mcp/authorize`, token URL `https://api.cueframe.ai/api/auth/mcp/token`)
  - API key in header `PAYMENT-SIGNATURE`

Returns the org this key is bound to (server-resolved from auth, never the body), the current plan, a per-feature `entitlements` map, and `costCeilings` (e.g. the generate_media per-call USD ceiling). Read it BEFORE a metered call (create_render / compose / generate_media / create_brand_kit) to budget without burning a round-trip on a 402. READ `balance`, NOT `included`: most capabilities are credit-funded — rendering, generation, previews, the judge and the Director carry no separate per-plan allowance and instead spend the shared wallet named in `fundedBy`, so each `balance` is that one wallet restated in the feature's own `unit`. Generation is also bounded by the disclosed generationLimit for accounts that have not purchased credits; `included:false` means the plan genuinely lacks the feature. Plan/entitlement values come from the billing backend best-effort; unknown values are `null` and `billingConfigured:false` flags an environment where billing isn't configured.

## Response `200`

The caller's account, plan, entitlements, and cost ceilings.

- AccountResponse: Account discovery for the authenticated key: identity + plan + entitlements + cost ceilings + the browser surfaces that exist. Read this to see what your plan/credits allow before a metered call (create_render / compose / generate_media / create_brand_kit).
  - `generationLimit` object, nullable, required: Separate lifetime generation cap before a credit-pack purchase. Wallet balance is still shared; generation must also fit this remaining provider-cost allowance. null means unknown.
    - `applies` boolean, required
    - `unit` 'cents_of_provider_cost', required
    - `cap` number, nullable, required
    - `spent` number, nullable, required
    - `remaining` number, nullable, required
  - `orgId` string, required: The org this API key is bound to — resolved server-side from the Authorization credential, NEVER from the request body/query.
  - `displayName` string, nullable, required: Org/customer display name from the billing record; null when not set or unknown.
  - `plan` object, nullable, required: The customer's current base plan/tier. null = unknown (billing not configured, or no active plan resolvable yet).
    - `id` string, required: Plan/product id (e.g. free, pro, business, studio).
    - `name` string, nullable, required: Plan display name.
  - `entitlements` object, required: Per-feature entitlements keyed by featureId. Covers the billing-gated capabilities: `exports` gates create_render AND generate_media output; `compose` gates compose; `brand_kits` gates create_brand_kit; `resource_import` gates import_resource (a boolean grant: `listUsdPerUnit` 0 — stock search and import cost no credits for a keyed caller); plus ai_tokens/storage/compose_verify/compose_capture/etc. Read `listUsdPerUnit` for what one unit costs before you spend it. Most capabilities are CREDIT-FUNDED — `included` is true and the real limit is `balance`, drawn from the shared wallet named in `fundedBy` (`credits` — generation included; a free org is additionally bounded by a generation cap). So read `balance`, not `included`, to decide whether you can afford a call; `included:false` means the plan genuinely lacks the feature. Check BEFORE a metered call to avoid a mid-workflow 402 billing_required (whose error `details.featureId` names the gating feature).
  - `costCeilings` object, required: Discoverable per-call cost ceilings so an agent can price/right-size a request before a guaranteed 402.
    - `generateMediaUsdPerCall` number, nullable, required: Per-call USD ceiling for generate_media: a generation whose ESTIMATE exceeds this 402s (generation_budget_exceeded) before any spend. Right-size the prompt/duration under this. null = unknown.
  - `billingConfigured` boolean, required: false = billing is not configured in this environment, so plan/entitlement values are best-effort and may be null (unknown), not authoritative.
  - `surfaces` object, required: The browser URLs that actually exist, so an agent asked to "show me" can hand the user a real link instead of guessing one from an id. A null means the surface is not built, not that it is hidden from this key.
    - `console` string, required: Origin of the authenticated web console.
    - `usage` string, required: Browser URL for the usage ledger.
    - `billing` string, required: Browser URL for plan and credits.
    - `apiKeys` string, required: Browser URL for minting and revoking API keys.
    - `project` unknown, required

## Other responses

- `401`: Missing or invalid Authorization header.
- `402`: Payment required. Returned when the caller presents no API key on a priced operation: the body AND the `Payment-Required` header carry the x402 v2 challenge (accepted scheme, network, USDC asset, amount, payTo). Sign the EIP-3009 authorization and retry with a `PAYMENT-SIGNATURE` header. A KEYED caller sees this status instead when their plan lacks or has exhausted the feature (`billing_required`).
- `403`: Forbidden — permission insufficient.
- `429`: Rate limited. Retry-After header present.
- `500`: Internal error.
- `503`: Service unavailable — billing_unavailable / honest-503 for runtime deps.

---

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