> ## Documentation Index > Fetch the complete documentation index at: https://docs.apimart.ai/llms.txt > Use this file to discover all available pages before exploring further. # Запрос расходов и использования > - Расходы и статистика вызовов за заданный период - Фильтрация по моделям, группировка по моделям и календарным дням - Статистика текущего API Key или всего аккаунта - Сумма в USD, кредиты, число вызовов и токены Запрашивайте расходы за заданный период с помощью API Key. Доступны фильтрация по моделям и группировка по моделям, календарным дням или обоим признакам. Результат агрегируется сразу: создавать задачу и опрашивать её статус не нужно. ```bash cURL theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'group_by=model' ``` ```python Python theme={null} import requests response = requests.get( "https://api.apimart.ai/v1/usage", headers={"Authorization": "Bearer "}, params={ "start": "2026-09-01T00:00:00+08:00", "end": "2026-09-08T00:00:00+08:00", "group_by": "model", }, timeout=30, ) payload = response.json() if not response.ok or not payload.get("success"): message = payload.get("error", {}).get("message", "Не удалось получить данные использования") raise RuntimeError(f"HTTP {response.status_code}: {message}") print(payload["data"]["total"]) print(payload["data"]["items"]) ``` ```javascript JavaScript theme={null} const url = new URL("https://api.apimart.ai/v1/usage"); url.search = new URLSearchParams({ start: "2026-09-01T00:00:00+08:00", end: "2026-09-08T00:00:00+08:00", group_by: "model", }).toString(); const response = await fetch(url, { headers: { Authorization: "Bearer " }, }); const payload = await response.json(); if (!response.ok || !payload.success) { throw new Error( `HTTP ${response.status}: ${payload.error?.message ?? "Не удалось получить данные использования"}`, ); } console.log(payload.data.total); console.log(payload.data.items); ``` ```json 200 theme={null} { "success": true, "data": { "scope": "key", "start": 1788192000, "end": 1788796800, "tz": "Asia/Shanghai", "group_by": "model", "total": { "amount_usd": 12.3456, "credits": 123.456, "requests": 1834, "prompt_tokens": 902311, "completion_tokens": 215044 }, "items": [ { "model": "gpt-5.6-luna", "amount_usd": 9.1271, "credits": 91.271, "requests": 1520, "prompt_tokens": 880120, "completion_tokens": 201300 }, { "model": "sora-2", "amount_usd": 3.2185, "credits": 32.185, "requests": 314, "prompt_tokens": 22191, "completion_tokens": 13744 } ] } } ``` ```json 400 theme={null} { "success": false, "error": { "code": "range_too_large", "message": "Time range must not exceed 31 days.", "type": "usage_query_error" } } ``` ## Аутентификация Используйте тот же API Key, что и для вызова моделей, с аутентификацией Bearer Token. Получить ключ можно на [странице управления API Key](https://apimart.ai/keys). ``` Authorization: Bearer YOUR_API_KEY ``` Запрос доступен при нулевом балансе. Баланс не проверяется, но проверяются статус и срок действия API Key, список разрешённых IP и статус аккаунта. ## Эндпоинты ```text theme={null} GET /v1/usage GET /usage ``` Оба эндпоинта имеют одинаковые функции и поддерживают CORS. Храните API Key безопасно и не раскрывайте его в публичном коде фронтенда. ## Параметры запроса Все параметры передаются в строке запроса URL. Время начала включается в период. Принимается Unix timestamp в секундах или строка RFC3339 с часовым поясом, например `2026-09-01T00:00:00+08:00`. По умолчанию — за 24 часа до `end`. Timestamp задаётся в секундах, не в миллисекундах. Время окончания не включается. Формат тот же, что у `start`; по умолчанию — текущее время. Должно быть позже `start`; `end - start` не может превышать 31 день. Название модели. Если не указано, учитываются все модели. Несколько моделей разделяются запятыми; максимум `50`. Точное совпадение без учёта регистра. Подстановочные знаки не поддерживаются. Пример: `gpt-5.6-luna,sora-2` Группировка: * `none`: только итог, `items` — пустой массив * `model`: по моделям * `date`: по календарным дням * `model,date`: по моделям и календарным дням Часовой пояс IANA. По умолчанию `Asia/Shanghai`. Влияет только на границы календарных дней, когда `group_by` содержит `date`, и не меняет моменты начала и окончания. Времена RFC3339 интерпретируются с указанным в них часовым поясом. Область статистики: * `key`: только текущий API Key (по умолчанию) * `account`: все API Key аккаунта, которому принадлежит текущий ключ Период — `[start, end)`: начало включается, окончание исключается. Одинаковое значение `end` предыдущего запроса и `start` следующего исключает двойной учёт границы. При ручном составлении URL кодируйте `+` в RFC3339 как `%2B`. cURL `--data-urlencode`, Python `params` и JavaScript `URLSearchParams` в примерах делают это автоматически. ## Примеры запросов ### Расходы текущего API Key за последние 24 часа Без параметров строки запроса используются период, область и группировка по умолчанию. ```bash theme={null} curl 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' ``` ### Ежедневные расходы всего аккаунта по выбранным моделям Запрос расходов с 11 по 18 сентября 2026 года по пекинскому времени, не включая 18 сентября. ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=1789056000' \ --data-urlencode 'end=1789660800' \ --data-urlencode 'model=gpt-5.6-luna' \ --data-urlencode 'group_by=date' \ --data-urlencode 'scope=account' \ --data-urlencode 'tz=Asia/Shanghai' ``` ### Группировка по моделям и календарным дням ```bash theme={null} curl --get 'https://api.apimart.ai/v1/usage' \ --header 'Authorization: Bearer ' \ --data-urlencode 'start=2026-09-01T00:00:00+08:00' \ --data-urlencode 'end=2026-09-08T00:00:00+08:00' \ --data-urlencode 'model=gpt-5.6-luna,sora-2' \ --data-urlencode 'group_by=model,date' \ --data-urlencode 'tz=Asia/Shanghai' ``` При этой группировке каждый элемент `items` содержит и `model`, и `date`. ## Поля ответа Успешность запроса: `true` при успехе, `false` при ошибке запроса использования. При успехе возвращает область запроса, итог и сгруппированные данные. Область статистики: `key` или `account`. Фактическое время начала: Unix timestamp в секундах, включительно. Фактическое время окончания: Unix timestamp в секундах, исключительно. Часовой пояс для группировки по календарным дням. Группировка: `none`, `model`, `date` или `model,date`. Итог за период запроса. Статистические поля приведены ниже. Сгруппированные данные по убыванию `amount_usd`. При `group_by=none` — пустой массив. Каждый элемент содержит статистические поля из таблицы ниже. * Если `group_by` содержит `model`, элемент содержит `model` * Если `group_by` содержит `date`, элемент содержит `date` в формате `YYYY-MM-DD`; границы дней определяются `tz` `data.total` и `data.items[]` используют следующие общие статистические поля: | Поле | Тип | Описание | | ------------------- | ------- | -------------------------------------------------------------------------------- | | `amount_usd` | number | Сумма в USD, округлённая до 6 знаков после запятой | | `credits` | number | Кредиты сервиса: `amount_usd × 10`, в тех же единицах, что на сайте | | `requests` | integer | Число успешно оплаченных вызовов | | `prompt_tokens` | integer | Входные токены; обычно 0 для изображений и видео с оплатой за вызов или секунду | | `completion_tokens` | integer | Выходные токены; обычно 0 для изображений и видео с оплатой за вызов или секунду | При ошибке запроса использования содержит `code`, `message` и `type`; `type` равен `usage_query_error`. Ошибки аутентификации 401 / 403 возвращает слой аутентификации. ## Лимиты и кеш * Не более `60` запросов в минуту на API Key; также действуют глобальные лимиты API * Результаты с одинаковыми параметрами кешируются на `60` секунд; заголовок `X-Usage-Cache` — `hit` или `miss` * Расходы обычно доступны в течение 1 секунды, но данные за последнюю минуту могут быть неполными; возможна задержка кеша * Рекомендуется интервал не менее 1 минуты; не используйте эндпоинт как уведомление о списаниях в реальном времени ## Правила учёта * Используются записи успешно оплаченных вызовов, как в панели данных на сайте * Неуспешные вызовы и возвраты после сбоя задачи исключены; вычитать их вручную не нужно. При частичном успехе пакета изображений оплачиваются фактически выданные изображения * Расходы относятся ко времени проведения платежа. Асинхронные задачи изображений и видео учитываются при завершении, не при отправке; при переходе через полночь — в день завершения * API Key, созданный заново после удаления, является новым ключом. Его запрос `scope=key` не включает историю старого ключа * Ручные корректировки баланса не являются расходами вызовов и исключаются * Доступны данные после 27 апреля 2026 года ## Обработка ошибок | Статус HTTP | `error.code` | Описание | | ----------- | ------------------------------- | ------------------------------------------------------------------------------- | | 400 | `invalid_start` / `invalid_end` | Неверный формат времени начала или окончания | | 400 | `invalid_range` | `end` не позже `start` | | 400 | `range_too_large` | Период превышает 31 день; разбейте его на несколько запросов | | 400 | `invalid_tz` | Неизвестный часовой пояс IANA | | 400 | `invalid_group_by` | Неверная группировка | | 400 | `invalid_scope` | Неверная область статистики | | 400 | `too_many_models` | Более 50 моделей | | 401 / 403 | — | Недействительный или просроченный API Key, IP не разрешён либо аккаунт отключён | | 429 | — | Более 60 запросов в минуту на ключ либо глобальный лимит API | | 503 | `usage_unavailable` | Данные временно недоступны; повторите позже | Ответ `503 usage_unavailable` не содержит сумм. Это означает недоступность запроса, а не нулевые расходы. Не заменяйте ошибку нулевой суммой и не перезаписывайте предыдущий успешный результат. ## Отличия от других эндпоинтов | Эндпоинт | Возможности | | --------------------------------- | ------------------------------------------------------------------------------- | | `GET /v1/dashboard/billing/usage` | Только накопленные расходы; без фильтров по моделям или времени | | `POST /v1/logs/export` | Асинхронный экспорт деталей вызовов (CSV / XLSX); агрегация на вашей стороне | | `GET /v1/usage` | Запрос по времени и моделям с прямым возвратом итога и сгруппированных расходов | Для оставшегося лимита используйте [запрос баланса токена](/ru/api-reference/account/token-balance) или [запрос баланса пользователя](/ru/api-reference/account/user-balance).