---
title: "GET /usage/{service} — Get Usage for Service"
url: https://lumean.app/developers/docs/api/get-usage-service
locale: ru
description: "Get Usage for Service"
generated: 2026-10-17
operationId: billing.usageService
method: GET
path: "/usage/{service}"
scopes: [billing.read]
spec_version: 0.0.1
---

# GET /usage/{service}

**Get Usage for Service**

То же, что `GET /usage`, но по одному сервису: расход, остаток и дата сброса счётчика.

Удобно проверить перед крупной задачей, хватит ли квоты. Неизвестный или недоступный
вам код сервиса → `404`.

**Требуемое право ключа:** `billing.read`.

- Право ключа: `billing.read`

## Запрос

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

## Параметры

| Поле | Где | Тип | Обяз. | Описание |
| --- | --- | --- | --- | --- |
| `service` | path | `string` | обяз. | Код сервиса — короткая латинская строка, а не число. Сейчас существуют: \| Код \| Что это \| \| --- \| --- \| \| `elevenlabs` \| Озвучка текста (TTS) на движке ElevenLabs \| \| `heygen` \| Озвучка текста (TTS) на движке HeyGen \| \| `cartesia` \| Озвучка текста (TTS) на движке Cartesia \| \| `fishaudio` \| Озвучка текста (TTS) на движке Fish Audio \| \| `lumimg` \| Генерация изображений \| \| `sfx` \| Звуковые эффекты \| \| `music` \| Музыкальные треки \| \| `voice_search` \| Подбор похожего голоса по загруженному аудиофрагменту \| **Где взять для своего аккаунта:** `GET /usage` возвращает `service_code` по каждому доступному вам сервису — это ровно те значения, которые примет этот путь. Тот же код лежит в поле `service_key` шаблона. Список открыт: при подключении нового сервиса в нём появляются новые коды, поэтому зашивать таблицу выше в клиент не стоит. Незнакомый либо недоступный вам код → `404`. default: `elevenlabs` |

## Тело запроса

Тела нет.

## Ответы

### 200 — Лимиты для сервиса

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Признак успеха. Решение принимайте по HTTP-коду: у любого ответа 2xx здесь `true`, а ошибка приходит телом другой формы, где этого поля может не быть вовсе. |
| `message` | `string` | обяз. | Пояснение для человека, на языке аккаунта. Показать пользователю можно; разбирать программно — нет: формулировки меняются без предупреждения и кодом ошибки не являются. |
| `data` | `array<object>` | обяз. | Лимиты по одному сервису — те же записи, что в `GET /usage`, но отфильтрованные. Обычно одна-две. |
| `data[].limit_id` | `integer` | обяз. | Идентификатор записи лимита. |
| `data[].service_id` | `integer` — nullable | обяз. | ID сервиса, к которому относится лимит. `null` у лимитов, не привязанных к сервису. |
| `data[].service_code` | `string` — nullable | обяз. | Код сервиса — то самое значение для пути `GET /usage/{service}` и для `service_key` шаблона. |
| `data[].service_name` | `string` — nullable | обяз. | Название сервиса для показа, на языке аккаунта. |
| `data[].entitlement_id` | `integer` — nullable | обяз. | ID возможности подписки, которая выдала этот лимит. |
| `data[].entitlement_code` | `string` — nullable | обяз. | Код возможности подписки, выдавшей лимит. |
| `data[].limit_type` | `string` | обяз. | Что именно ограничивается. Две принципиально разные вещи: - **периодическая квота** — расход за период, обнуляется по `period_end`; - **слоты одновременных задач** — освобождаются сами, как только ваши текущие заказы завершатся. Исчерпание первой ждёт конца периода, второй — минут. |
| `data[].limit_value` | `integer` — nullable | обяз. | Потолок по текущей подписке. `null` — потолка нет (см. `token_unlimited`). |
| `data[].used` | `integer` | обяз. | Сколько израсходовано в текущем периоде. |
| `data[].remaining` | `integer` — nullable | обяз. | Сколько осталось. `null` при безлимите. |
| `data[].period_start` | `string` — nullable | обяз. | Начало текущего периода учёта, ISO 8601. `null`, если учёт в текущем периоде ещё не открыт (`used` при этом 0): лимит не трогали вовсе либо тратили только в прошлых периодах — период открывается первым расходом, а не по календарю. |
| `data[].period_end` | `string` — nullable | обяз. | Конец текущего периода учёта, ISO 8601 — в этот момент счётчик обнулится. `null` там же, где `period_start` (учёт в текущем периоде ещё не открыт), и у лимитов без периода (`concurrent`, `total`). |
| `data[].resets_in` | `string` — nullable | обяз. | Сколько осталось до сброса счётчика, в человекочитаемом виде. `null` там же, где `period_end`. |
| `data[].token_unlimited` | `boolean` | обяз. | `true` — токены по этому сервису не ограничены. Ограничение на одновременные задачи это НЕ снимает. |
| `data[].is_exceeded` | `boolean` | обяз. | Лимит исчерпан: следующий заказ по этому сервису будет отклонён, пока счётчик не сбросится или не освободится слот. |
| `data[].usage_percentage` | `number` | обяз. | Доля израсходованного, 0–100. При безлимите всегда 0. |

**Пример**

```json
{
  "success": true,
  "message": "Success",
  "data": [
    {
      "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 — Невалидный или отсутствующий API-ключ

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |
| `data` | `null` — nullable | обяз. | Всегда `null`, когда запрос отклонён до обработки. |

**Пример**

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

### 403 — У ключа нет права billing.read

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `success` | `boolean` | обяз. | Всегда `false` в ответах об ошибке. |
| `message` | `string` | обяз. | Текст ошибки на языке ключа (задаётся заголовком `X-Locale`). |

**Пример**

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

### 404 — Сервис не найден

**Поля ответа**

| Поле | Тип | Обяз. | Описание |
| --- | --- | --- | --- |
| `message` | `string` | обяз. | Error overview. |

**Пример**

```json
{
  "success": false,
  "message": "Resource not found."
}
```

---

- Эта же страница в браузере: https://lumean.app/developers/docs/api/get-usage-service
- Машинный справочник целиком: https://api.lumean.app/docs/llm.md