> ## 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 поточного облікового запису за останні 60 днів; це підходить для перевірки списань, виявлення невдалих запитів і пошуку проблем за сервісом, Application, API або обліковими даними.

> На цій сторінці запитуються власні журнали викликів облікового запису. Якщо ви хочете переглянути лише загальнодоступну статистику викликів певного API на всій платформі, використовуйте [Статистику викликів API](https://platform.acedata.cloud/documents/platform-api-usage).

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

### 1. Створення токена облікового запису

Цей інтерфейс належить до API керування платформою, потрібно використовувати **Account Token (токен облікового запису)**:

1. Увійдіть на [платформу AceDataCloud](https://platform.acedata.cloud).
2. Відкрийте [консоль Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. Натисніть «Створити», одразу збережіть токен у менеджері паролів або Secret Manager.

Повний опис див. у розділі [Керування токенами облікового запису платформи AceDataCloud](https://platform.acedata.cloud/documents/platform-token). Токени облікового запису використовуються для `platform.acedata.cloud/api/v1/**`; для виклику бізнес-інтерфейсів `api.acedata.cloud/**` використовуються облікові дані API (Credential), їх не можна змішувати.

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

Не записуйте токен у фронтенд-код, журнали або публічні репозиторії; у разі витоку негайно видаліть його в консолі та створіть заново.

### 2. Підготовка ID для фільтрації (необов’язково)

Без передавання умов фільтрації можна переглядати записи, які поточний обліковий запис має право переглядати. Якщо потрібно звузити діапазон:

* `application_id`: отримайте зі [списку заявок на сервіс](https://platform.acedata.cloud/documents/platform-application-list);
* `credential_id`: отримайте зі [списку облікових даних API](https://platform.acedata.cloud/documents/platform-credential-list);
* `api_id`: отримайте зі [списку API](https://platform.acedata.cloud/documents/platform-api-list);
* `service_id`: отримайте зі [списку сервісів](https://platform.acedata.cloud/documents/platform-service-list).

Звичайним користувачам не потрібно передавати `user_id`; якщо його передано явно, він має збігатися з поточним обліковим записом, інакше повертається `403`. Адміністратори можуть використовувати цей параметр для фільтрації між обліковими записами.

## Огляд інтерфейсу

| Пункт | Вміст |
| - | - |
| Метод | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Автентифікація | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` може включати) |
| Пагінація | `count` + `items`, за замовчуванням 10 записів на сторінку |

## Область запиту

| `perspective` | Значення |
| - | - |
| `both` | Значення за замовчуванням; повертає записи, за які поточний обліковий запис сплачує або які фактично викликає |
| `billing` | Повертає лише записи, за які сплачує поточний обліковий запис |
| `actor` | Повертає лише записи, фактично викликані поточним обліковим записом |

## Параметри запиту

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
| - | - | - | - | - |
| `perspective` | string | Ні | `both` | `billing`, `actor` або `both` |
| `user_id` | UUID | Ні | — | Лише адміністратори можуть фільтрувати за користувачем; підтримуються повторювані параметри |
| `service_id` | UUID | Ні | — | Фільтрація за сервісом; підтримуються повторювані параметри |
| `application_id` | UUID | Ні | — | Фільтрація за Application; підтримуються повторювані параметри |
| `api_id` | UUID | Ні | — | Фільтрація за API; підтримуються повторювані параметри |
| `credential_id` | UUID | Ні | — | Фільтрація за обліковими даними API; підтримуються повторювані параметри |
| `status_code` | integer | Ні | — | Фільтрація за кодом статусу HTTP; підтримуються повторювані або розділені комами значення |
| `created_at_from` | datetime | Ні | — | Нижня межа часу створення, ISO 8601 |
| `created_at_to` | datetime | Ні | — | Верхня межа часу створення, ISO 8601 |
| `limit` | integer | Ні | 10 | Кількість записів на сторінку, максимум 100 |
| `offset` | integer | Ні | 0 | Зміщення пагінації |
| `ordering` | string | Ні | `-created_at` | За спаданням часу створення |

Якщо час запиту раніший за останні 60 днів, інтерфейс повертає помилку валідації поля `400`, вказуючи, що повні деталі викликів зберігаються лише 60 днів.

## Приклади запитів

Запит останніх 100 записів:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode 'perspective=both' \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Фільтрація за часом, Application і статусом помилки:

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

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Приклад пагінації Python:

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

url = "https://platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])
```

## Приклад відповіді

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}
```

## Ключові поля

| Поле | Опис |
| - | - |
| `user_id` | Обліковий запис, з якого стягується плата за цей виклик |
| `actor_user_id` | Обліковий запис, який фактично ініціював виклик; може відрізнятися від `user_id` під час надання іншим особам дозволу на використання облікових даних |
| `used_amount` | Обсяг використання цього виклику, розрахований за початковими правилами |
| `original_amount` | Початковий обсяг використання до застосування знижки |
| `deducted_amount` | Обсяг, який фактично остаточно списано |
| `remaining_amount` | Залишковий ліміт Application після завершення цього списання |
| `elapsed` | Тривалість виклику, зафіксована сервером, у секундах |
| `trace_id` | Ідентифікатор відстеження, що використовується для діагностики одного запиту |
| `metadata` | Загальнодоступні метадані; список не повертає повний вміст запиту або відповіді |
| `api` / `service` / `credential` | Зведення пов’язаних об’єктів для зручного відображення; може бути порожнім, якщо пов’язаний об’єкт більше не існує |

Одиниця ліміту визначається `service.unit` відповідного Application і не повинна за замовчуванням вважатися доларами США.

## Помилки та повторні спроби

| HTTP | `error` | Значення | Спосіб обробки |
| - | - | - | - |
| 400 | Помилка перевірки поля | Діапазон запиту раніший за 60-денний період зберігання | Налаштуйте час початку в межах останніх 60 днів |
| 401 | `not_authenticated` | Токен облікового запису відсутній або недійсний | Перевірте Account Token, не використовуйте помилково бізнес Credential |
| 403 | `permission_denied` | Запит містить записи, на перегляд яких немає прав | Видаліть неавторизовані умови фільтрації користувачів |
| 429 | `usage_query_in_progress` | Цілком ідентичний запит усе ще виконується | Зачекайте `Retry-After`, а потім виконайте повторну спробу з експоненційною затримкою |
| 503 | `usage_query_timeout` | Запит перевищив безпечний часовий ліміт сервера | Зменште часовий діапазон або додайте умови фільтрації, а потім повторіть спробу |

Для одного набору параметрів запиту дозволяється не більше одного запиту в процесі виконання. Для запитів великого діапазону перевагу слід надавати вікнам у один день або меншим; не накладайте ідентичні запити з фіксованими інтервалами.

## Наступний крок

* [Агрегувати обсяг викликів](https://platform.acedata.cloud/documents/platform-usage-aggregate)：перегляньте обсяг використання, підсумований за датою та API.
* [Експортувати обсяг викликів](https://platform.acedata.cloud/documents/platform-usage-export)：завантажте велику кількість деталей безпосередньо як CSV.
* [Переглянути записи викликів Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage)：запитуйте записи для сервісів типу Proxy.
* [Переглянути деталі заявки на сервіс](https://platform.acedata.cloud/documents/platform-application-detail)：перевірте баланс і одиницю ліміту.
* [Ротуйте облікові дані API](https://platform.acedata.cloud/documents/platform-credential-rotate)：негайно замініть їх у разі підозри на витік облікових даних.


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