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