> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# Получение агрегированной статистики вызовов API платформы AceDataCloud

> Platform API guide - Ace Data Cloud

Сводка количества запросов и фактически списанных лимитов текущего аккаунта по датам и API, подходит для создания ежемесячных отчетов, графиков трендов и анализа затрат. Для построчного поиска ошибок используйте [список записей вызовов](https://platform.acedata.cloud/documents/platform-usage-list), для полных офлайн-деталей используйте [экспорт объема вызовов](https://platform.acedata.cloud/documents/platform-usage-export)。

## Подготовка

1. Войдите на [платформу AceDataCloud](https://platform.acedata.cloud)。
2. Создайте токен аккаунта в [консоли Account Token](https://platform.acedata.cloud/console/platform-tokens) и немедленно сохраните его。
3. Если необходимо сузить область, получите соответствующий ID из [списка заявок на сервисы](https://platform.acedata.cloud/documents/platform-application-list)、[списка учетных данных API](https://platform.acedata.cloud/documents/platform-credential-list) или [списка API](https://platform.acedata.cloud/documents/platform-api-list)。

Полное описание токенов см. в разделе [Управление токенами аккаунта](https://platform.acedata.cloud/documents/platform-token)。Этот интерфейс использует Account Token, а не бизнесовый Credential。

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

## Обзор интерфейса

| Пункт | Содержание |
| - | - |
| Метод | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Аутентификация | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform` могут расширенно включать） |
| Область прав | Для обычных пользователей фиксирована на их платном использовании; администраторы могут передавать `user_id` |

## Параметры запроса

| Параметр | Тип | Обязателен | По умолчанию | Описание |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Нет | Первый день текущего месяца в выбранном часовом поясе | Время начала, рекомендуемое имя параметра |
| `created_at_to` | date / datetime | Нет | Текущее время | Время окончания, рекомендуемое имя параметра |
| `timezone` | string | Нет | `UTC` | Часовой пояс IANA, например `Asia/Shanghai`; недопустимое значение возвращается к UTC |
| `service_id` | UUID | Нет | — | Фильтрация по сервису; поддерживаются повторяющиеся параметры |
| `application_id` | UUID | Нет | — | Фильтрация по Application; поддерживаются повторяющиеся параметры |
| `api_id` | UUID | Нет | — | Фильтрация по API; поддерживаются повторяющиеся параметры |
| `credential_id` | UUID | Нет | — | Фильтрация по учетным данным API; поддерживаются повторяющиеся параметры |
| `include_models` | boolean | Нет | `false` | Нужно ли дополнительно вычислять сводку по измерению моделей; увеличивает стоимость запроса |
| `user_id` | UUID | Нет | Для обычных пользователей фиксировано на себе; если администратор не передает — все аккаунты | Только администраторы могут указывать любой аккаунт |

`start_time` / `end_time` по-прежнему можно использовать как совместимые псевдонимы для старых клиентов, в новых интеграциях единообразно используйте `created_at_from` / `created_at_to`。Форма даты `created_at_to` включает этот календарный день, то есть использует ноль часов следующего дня как границу。

## Примеры запросов

Запрос ежедневной/API-сводки за текущий месяц по пекинскому времени с добавлением измерения моделей:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Запрос использования за неделю для указанного Application:

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Пример Python:

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## Пример ответа

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

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

| Поле | Описание |
| - | - |
| `items` | Группировка по дате выбранного часового пояса и `api_id`; каждая строка содержит `date`、`api_id`、`amount` |
| `total` | Сумма `deducted_amount` в диапазоне запроса |
| `apis` | Сопоставление ID API со сводкой заголовков, удобно для отображения `items` |
| `requests` | Общее количество запросов в диапазоне запроса |
| `models` | Вычисляется только при `include_models=true`; каждый элемент содержит `model`、`amount`、`requests` |

Единица лимита зависит от `service.unit` соответствующего Application。Если запрос содержит сервисы с разными единицами, сначала ведите раздельную статистику по `service_id` или `application_id`, чтобы избежать прямого сравнения или сложения。

Когда время окончания не больше времени начала, интерфейс возвращает полную пустую структуру: `items=[]`、`total=0`、`apis={}`、`requests=0`、`models=[]`。

## Рекомендации по ошибкам и производительности

| HTTP | `error` | Способ обработки |
| - | - | - |
| 400 | `usage_history_expired` | Скорректируйте диапазон времени на период после `available_from` в ответе |
| 401 | `not_authenticated` | Проверьте Account Token, не используйте по ошибке бизнесовый Credential |
| 403 | `permission_denied` | Обычные пользователи не могут запрашивать другие аккаунты |

* По умолчанию не включайте `include_models`; включайте его только когда отчету действительно требуется разбивка по моделям。
* Для запросов большого диапазона в первую очередь разделяйте данные по `service_id` или `application_id`, это одновременно предотвращает смешивание единиц и снижает стоимость запроса。
* Даты без вызовов не дополняются нулями автоматически, перед построением графика клиент должен дополнить ось дат。

## Следующий шаг

* [Просмотреть записи вызовов](https://platform.acedata.cloud/documents/platform-usage-list)：определить детали, составляющие агрегированный результат.
* [Экспортировать объём вызовов](https://platform.acedata.cloud/documents/platform-usage-export)：скачать полные детали в формате CSV.
* [Просмотреть детали заявки на сервис](https://platform.acedata.cloud/documents/platform-application-detail)：подтвердить баланс и единицу измерения.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.