---
title: "GET /usage — Get Usage Limits"
url: https://lumean.app/en/developers/docs/api/get-usage
locale: en
description: "Get Usage Limits"
generated: 2026-10-17
operationId: billing.usage
method: GET
path: /usage
scopes: [billing.read]
spec_version: 0.0.1
---

# GET /usage

**Get Usage Limits**

A summary of every limit for the key owner: how much has been consumed, the ceiling
granted by the current subscription, the limit type and when the counter resets.

It also shows which services are available to you at all — the set is defined by the
entitlements of the active subscription.

Do not conflate the two limit types: a periodic quota (resets at `reset_at`) and
concurrent task slots (freed as soon as your running orders finish). Exhausting the
first means waiting for the period to end; the second, only minutes.

**Required key permission:** `billing.read`.

- Required scope: `billing.read`

## Request

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

## Parameters

No parameters.

## Request body

No body.

## Responses

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

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | 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` | required | 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` | `array<object>` | required | One record per limit granted by your subscription. An empty list means there is no active subscription and generation is unavailable. |
| `data[].limit_id` | `integer` | required | Identifier of the limit record. |
| `data[].service_id` | `integer` — nullable | required | ID of the service the limit applies to. `null` for limits not tied to a service. |
| `data[].service_code` | `string` — nullable | required | Service code — the value for the `GET /usage/{service}` path and for a template’s `service_key`. |
| `data[].service_name` | `string` — nullable | required | Service name for display, in the account language. |
| `data[].entitlement_id` | `integer` — nullable | required | ID of the subscription entitlement that granted this limit. |
| `data[].entitlement_code` | `string` — nullable | required | Code of the subscription entitlement that granted the limit. |
| `data[].limit_type` | `string` | required | What exactly is being capped. Two fundamentally different things: - a **periodic quota** — consumption over a period, reset at `period_end`; - **concurrent-task slots** — freed on their own as soon as your running orders finish. Exhausting the first means waiting for the period to end; the second, minutes. |
| `data[].limit_value` | `integer` — nullable | required | The ceiling under the current subscription. `null` means there is no ceiling (see `token_unlimited`). |
| `data[].used` | `integer` | required | How much has been consumed in the current period. |
| `data[].remaining` | `integer` — nullable | required | How much is left. `null` when unlimited. |
| `data[].period_start` | `string` — nullable | required | Start of the current accounting period, ISO 8601. `null` while no accounting period is open yet (`used` is then 0): the limit was never touched, or was consumed only in past periods — a period opens with the first consumption, not by the calendar. |
| `data[].period_end` | `string` — nullable | required | End of the current accounting period, ISO 8601 — the counter resets at that moment. `null` wherever `period_start` is `null` (no period open yet) and for limits without a period (`concurrent`, `total`). |
| `data[].resets_in` | `string` — nullable | required | Time left until the counter resets, in human-readable form. `null` whenever `period_end` is `null`. |
| `data[].token_unlimited` | `boolean` | required | `true` means tokens for this service are unlimited. It does **not** lift the cap on concurrent tasks. |
| `data[].is_exceeded` | `boolean` | required | The limit is exhausted: the next order for this service is rejected until the counter resets or a slot frees up. |
| `data[].usage_percentage` | `number` | required | Share consumed, 0–100. Always 0 when unlimited. |

**Example**

```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "limit_id": 10,
      "service_id": 1,
      "service_code": "sfx",
      "service_name": "Sound Effects",
      "entitlement_id": null,
      "entitlement_code": null,
      "limit_type": "hourly",
      "limit_value": 100,
      "used": 0,
      "remaining": 100,
      "period_start": null,
      "period_end": null,
      "resets_in": null,
      "token_unlimited": false
    },
    {
      "limit_id": 11,
      "service_id": 2,
      "service_code": "music",
      "service_name": "Music Generation",
      "entitlement_id": null,
      "entitlement_code": null,
      "limit_type": "hourly",
      "limit_value": 100,
      "used": 0,
      "remaining": 100,
      "period_start": null,
      "period_end": null,
      "resets_in": null,
      "token_unlimited": false
    },
    {
      "limit_id": 12,
      "service_id": 3,
      "service_code": "elevenlabs",
      "service_name": "ElevenLabs TTS",
      "entitlement_id": 2,
      "entitlement_code": "elevenlabs_tts",
      "limit_type": "monthly",
      "limit_value": 500000,
      "used": 128400,
      "remaining": 371600,
      "period_start": "2026-07-01T00:00:00+00:00",
      "period_end": "2026-08-01T00:00:00+00:00",
      "resets_in": "2 weeks from now",
      "token_unlimited": false
    }
  ]
}
```

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

**Response fields**

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

**Example**

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

**Response fields**

| Field | Type | Req. | Description |
| --- | --- | --- | --- |
| `success` | `boolean` | required | Always `false` in error responses. |
| `message` | `string` | required | Error text in the key's language (set through the `X-Locale` header). |

**Example**

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

---

- This page in the browser: https://lumean.app/en/developers/docs/api/get-usage
- Full machine-readable reference: https://api.lumean.app/docs/llm.md