Public API для биллинга

Запрашивайте баланс аккаунта, использование моделей и расходы из своих биллинговых инструментов

Public API для биллинга позволяет читать данные биллинга Atlas Cloud из скриптов, дашбордов и финансовых систем.

Base URL: https://api.atlascloud.ai/public/v1

Endpoints

Endpoint	Описание
`GET /balance`	Текущий баланс аккаунта и сводка кредитов
`GET /model-usage`	Дневные buckets использования моделей
`GET /model-costs`	Дневные buckets расходов по моделям

Полные схемы запросов и ответов доступны в API reference:

Аутентификация

Передайте Atlas Cloud API Key в header Authorization:

Authorization: Bearer apikey-...

Создайте ключи в API Keys. Секретный ключ начинается с apikey-.

Некоторые ответы и фильтры используют public ID API Key вида ak_.... Этот ID можно показывать в отчетах, но он не является credential.

Права доступа

/model-usage и /model-costs по умолчанию используют scope=self и возвращают usage, связанный с аутентифицированным пользователем, включая принадлежащие ему API Keys.

Используйте scope=account, чтобы запросить использование и расходы всего аккаунта. Для этого нужна account-level model billing read permission. /balance всегда использует account scope и требует account balance read permission.

Владельцы персональных аккаунтов могут читать свои данные. Для team accounts используйте роль Account Admin или Finance.

Запрос Баланса

curl "https://api.atlascloud.ai/public/v1/balance" \
  -H "Authorization: Bearer apikey-..."

Денежные значения возвращаются строками с шестью знаками после запятой и валютой:

{
  "value": "125.500000",
  "currency": "usd"
}

Параметры Использования и Расходов

start_date и end_date обязательны, задаются в UTC и формате YYYY-MM-DD. end_date эксклюзивен, максимальный диапазон — 180 дней.

Общие query-параметры для /model-usage и /model-costs. Если не передавать group_by[], возвращаются дневные итоги:

Параметр	Описание
`start_date`	Начальная дата UTC включительно в формате `YYYY-MM-DD`
`end_date`	Конечная дата UTC не включается, формат `YYYY-MM-DD`; диапазон может охватывать максимум 180 дней
`scope`	`self` или `account`; по умолчанию `self`
`group_by[]`	Необязательная группировка. Поддерживаемые наборы: `model_type`, `model`, `api_key` или `model` плюс `api_key`; для разбивки по моделям используйте `group_by[]=model`
`model_types[]`	Повторяйте с `text`, `image` или `video`
`model_ids[]`	Фильтр по ID моделей; максимум 100 значений
`api_key_ids[]`	Фильтр по public IDs `ak_...`; максимум 100 значений
`limit`	Строк на страницу, от 1 до 1000; по умолчанию 100
`page`	Непрозрачный cursor из `next_page`

Для массивов используйте повторяющиеся параметры. Значения через запятую отклоняются.

Запрос Использования

Ответ по умолчанию возвращает дневные итоги использования.

curl "https://api.atlascloud.ai/public/v1/model-usage?start_date=2026-05-01&end_date=2026-05-08" \
  -H "Authorization: Bearer apikey-..."

Запрос Расходов

/model-costs принимает тот же диапазон дат, scope, фильтры, группировку и параметры пагинации, что и /model-usage. Если не передавать group_by[], возвращаются дневные итоги расходов.

curl "https://api.atlascloud.ai/public/v1/model-costs?start_date=2026-05-01&end_date=2026-05-08&scope=account&group_by[]=model&group_by[]=api_key" \
  -H "Authorization: Bearer apikey-..."

Пагинация

Когда has_more равно true, передайте next_page без изменений как query-параметр page. Cursor непрозрачен: не декодируйте его и не меняйте остальные параметры.

Ошибки и Лимиты

Ошибки используют стабильный envelope:

{
  "error": {
    "type": "invalid_request_error",
    "code": "invalid_date",
    "message": "start_date must be YYYY-MM-DD",
    "param": "start_date"
  },
  "request_id": "req_..."
}

При rate limit возвращается 429 rate_limit_error; ответ может содержать header Retry-After.

Public API для биллинга

Содержание