---
title: "GET /subscriptions — Get subscriptions of API key owner"
url: https://lumean.app/de/developers/docs/api/get-subscriptions
locale: de
description: "Get subscriptions of API key owner"
generated: 2026-10-17
operationId: subscription.index
method: GET
path: /subscriptions
scopes: [billing.read]
spec_version: 0.0.1
---

# 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.

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`.

- Benötigtes Recht: `billing.read`

## Anfrage

```bash
curl -X GET 'https://api.lumean.app/api/public/subscriptions' \
  -H 'Accept: application/json' \
  -H 'X-API-KEY: YOUR_API_KEY'
```

## Parameter

Keine Parameter.

## Request-Body

Kein Body.

## Antworten

### 200 — Success. The payload is in `data`.

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `success` | `boolean` | Pflicht | 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. |
| `message` | `string` | Pflicht | 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. |
| `data` | `object` | Pflicht | The response payload. |
| `data.available_models` | `array<string>` | Pflicht | Codes of the models your active subscriptions grant. A model outside this list is rejected when creating an order. |
| `data.subscriptions` | `array<object>` | Pflicht | Your subscriptions. An empty list means there is no active subscription: orders are then possible only with a positive LMC balance. |
| `data.subscriptions[].id` | `integer` | Pflicht | Subscription identifier. |
| `data.subscriptions[].status` | `string` | Pflicht | Subscription state. There is no auto-renewal: once the term ends the subscription expires and the plan has to be purchased again. |
| `data.subscriptions[].current_period_start` | `string` | Pflicht | Start of the current period, ISO 8601. |
| `data.subscriptions[].current_period_end` | `string` | Pflicht | End of the current period, ISO 8601 — the moment the subscription expires. |
| `data.subscriptions[].items` | `array<object>` | Pflicht | The plans inside the subscription: what was purchased and how many tokens are left. |
| `data.subscriptions[].items[].plan` | `object` | Pflicht | The purchased plan: code and name. |
| `data.subscriptions[].items[].plan.code` | `string` | Pflicht | Plan code. |
| `data.subscriptions[].items[].plan.name` | `string` | Pflicht | Display name of the plan. |
| `data.subscriptions[].items[].status` | `string` | Pflicht | State of the plan within the subscription. |
| `data.subscriptions[].items[].is_usable` | `boolean` | Pflicht | Whether this plan can be spent right now. **Branch on this**, not on `status`: a plan can be formally active yet already exhausted. |
| `data.subscriptions[].items[].billing_period` | `string` | Pflicht | Billing period. Only monthly is supported. |
| `data.subscriptions[].items[].start_at` | `string` | Pflicht | When the plan took effect, ISO 8601. |
| `data.subscriptions[].items[].end_at` | `string` | Pflicht | When the plan expires, ISO 8601. Any remaining tokens are forfeited after that moment. |
| `data.subscriptions[].items[].token_allowance` | `integer` | Pflicht | How many tokens the plan grants per period. |
| `data.subscriptions[].items[].tokens_used` | `integer` | Pflicht | How many tokens have been consumed in the current period. |
| `data.subscriptions[].items[].tokens_remaining` | `integer` | Pflicht | How many tokens are left. This balance is spent **before** any LMC is charged — a top-up kicks in only once it runs out. |

**Beispiel**

```json
{
  "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
          }
        ]
      }
    ]
  }
}
```

### 401 — The key is missing, unknown, disabled or expired.

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `success` | `boolean` | Pflicht | Always `false` in error responses. |
| `message` | `string` | Pflicht | Error text in the key's language (set through the `X-Locale` header). |
| `data` | `null` — nullable | Pflicht | Always `null` when the request is rejected before processing. |

**Beispiel**

```json
{
  "success": false,
  "message": "API key is missing. Provide it in the X-API-KEY header.",
  "data": null
}
```

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

**Antwortfelder**

| Feld | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `success` | `boolean` | Pflicht | Always `false` in error responses. |
| `message` | `string` | Pflicht | Error text in the key's language (set through the `X-Locale` header). |

**Beispiel**

```json
{
  "success": false,
  "message": "This API key does not have permission to perform this action."
}
```

---

- Diese Seite im Browser: https://lumean.app/de/developers/docs/api/get-subscriptions
- Vollständige maschinenlesbare Referenz: https://api.lumean.app/docs/llm.md