Skip to content
Lumean API
GET/subscriptions

Get subscriptions of API key owner

Returns the key owner's subscriptions together with the remaining token balance and the models each plan unlocks.

billing.read

This is the primary way to answer "how much generation do I have left" before submitting a large job.

Subscriptions do not auto-renew: an expired one simply stops working, and a new one is purchased through the web interface.

Required key permission: billing.read.

On this page(2)

Possible responses

200

Success. The payload is in data.

Body example
{
  "success": true,
  "message": "Success",
  "data": {
    "available_models": [
      "gpt-4.1-mini",
      "claude-haiku-4.5"
    ],
    "subscriptions": [
      {
        "id": 301,
        "status": "active",
        "current_period_start": "2026-07-15T00:00:00+00:00",
        "current_period_end": "2026-08-15T00:00:00+00:00",
        "items": [
          {
            "plan": {
              "code": "creator",
              "name": "Creator"
            },
            "status": "active",
            "is_usable": true,
            "billing_period": "monthly",
            "start_at": "2026-07-15T00:00:00+00:00",
            "end_at": "2026-08-15T00:00:00+00:00",
            "token_allowance": 30000,
            "tokens_used": 8200,
            "tokens_remaining": 21800
          }
        ]
      }
    ]
  }
}
Response fields
successrequired

Success flag. Branch on the HTTP status code instead: any 2xx response carries true here, while an error comes back in a different shape that need not contain this field at all.

boolean
messagerequired

A human-readable note in the account language. Fine to show to a user; do not parse it — the wording changes without notice and is not an error code.

string
datarequired

The response payload.

object
available_modelsrequired

Codes of the models your active subscriptions grant. A model outside this list is rejected when creating an order.

array<string>
subscriptionsrequired

Your subscriptions. An empty list means there is no active subscription: orders are then possible only with a positive LMC balance.

array<object>
array item
idrequired

Subscription identifier.

integer
statusrequired

Subscription state. There is no auto-renewal: once the term ends the subscription expires and the plan has to be purchased again.

string
current_period_startrequired

Start of the current period, ISO 8601.

string
current_period_endrequired

End of the current period, ISO 8601 — the moment the subscription expires.

string
itemsrequired

The plans inside the subscription: what was purchased and how many tokens are left.

array<object>
array item
planrequired

The purchased plan: code and name.

object
coderequired

Plan code.

string
namerequired

Display name of the plan.

string
statusrequired

State of the plan within the subscription.

string
is_usablerequired

Whether this plan can be spent right now. Branch on this, not on status: a plan can be formally active yet already exhausted.

boolean
billing_periodrequired

Billing period. Only monthly is supported.

string
start_atrequired

When the plan took effect, ISO 8601.

string
end_atrequired

When the plan expires, ISO 8601. Any remaining tokens are forfeited after that moment.

string
token_allowancerequired

How many tokens the plan grants per period.

integer
tokens_usedrequired

How many tokens have been consumed in the current period.

integer
tokens_remainingrequired

How many tokens are left. This balance is spent before any LMC is charged — a top-up kicks in only once it runs out.

integer
401

The key is missing, unknown, disabled or expired.

Analyse this response
Body example
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string
datarequired

Always null when the request is rejected before processing.

nullable
null
403

The key lacks the required permission, or the object belongs to another user.

Analyse this response
Body example
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
Response fields
successrequired

Always false in error responses.

boolean
messagerequired

Error text in the key's language (set through the X-Locale header).

string

Nearby

Feed this page to an AI

Open .mdllm.md

spec 0.0.1