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

# Отримання записів викликів Proxy платформи AceDataCloud

> Platform API guide - Ace Data Cloud

Запит записів про використання поточного облікового запису в сервісах типу Proxy. Для звичайних викликів API використовуйте [Записи викликів API](https://platform.acedata.cloud/documents/platform-usage-list). Якщо тип сервісу невідомий, спочатку перегляньте `type` у [відомостях про сервіс](https://platform.acedata.cloud/documents/platform-service-detail).

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

1. Увійдіть на [платформу AceDataCloud](https://platform.acedata.cloud).
2. Створіть токен облікового запису в [консолі Account Token](https://platform.acedata.cloud/console/platform-tokens) і негайно збережіть його в менеджері паролів або Secret Manager.
3. Відкрийте [сторінку профілю](https://auth.acedata.cloud/user/profile), скопіюйте UUID поточного облікового запису та збережіть його як `USER_ID`. Також можна використати `user_id` з відповіді на створення токена облікового запису.
4. Отримайте `application_id` сервісу типу Proxy зі [списку заявок на сервіс](https://platform.acedata.cloud/documents/platform-application-list). Якщо потрібно фільтрувати за кінцевою точкою Proxy, отримайте `proxy_id` зі [списку Proxy сервісу](https://platform.acedata.cloud/documents/platform-service-proxies).

Повний опис токенів дивіться в [Керування токенами облікового запису](https://platform.acedata.cloud/documents/platform-token). Цей інтерфейс використовує Account Token, а не Credential для виклику бізнес-API.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

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

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

Коли власник Application виконує запит за `application_id`, сервер спочатку синхронізує доступні записи цього Application, а потім повертає список, тому час відповіді може бути довшим, ніж для звичайного списку API usage. Авторизовані користувачі можуть читати наявні видимі записи, але це не запускає синхронізацію на стороні власника.

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

| Параметр | Тип | Обов’язковий | За замовчуванням | Опис |
| - | - | - | - | - |
| `user_id` | UUID | обов’язковий для звичайних користувачів | — | UUID поточного облікового запису; передавання іншого облікового запису поверне `403` |
| `application_id` | UUID | рекомендовано | — | Фільтрація за Proxy Application; підтримує повторювані параметри |
| `proxy_id` | UUID | ні | — | Фільтрація за кінцевою точкою Proxy; підтримує повторювані параметри |
| `limit` | integer | ні | 10 | Кількість записів на сторінку, максимум 100 |
| `offset` | integer | ні | 0 | Зсув пагінації |
| `ordering` | string | ні | `-created_at` | За спаданням часу створення |

Поточний інтерфейс не підтримує пряме фільтрування за моделлю, HTTP-кодом стану, Credential або часовим діапазоном, а також не підтримує параметр `perspective` інтерфейсу API usage. Не додавайте до запиту ці непідтримувані параметри й не припускайте, що вони набули чинності.

## Приклад запиту

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

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

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

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

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

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

| Поле | Опис |
| - | - |
| `user_id` | Обліковий запис, з якого стягується плата за цей виклик |
| `actor_user_id` | Фактичний викликач; старі записи можуть бути порожніми |
| `application_id` | Proxy Application, що створив цей запис |
| `proxy_id` | Відповідна кінцева точка Proxy |
| `credential_id` | ID пов’язаного облікового даного; старі записи можуть бути порожніми |
| `used_amount` | Використання в оригінальному записі; може бути порожнім |
| `deducted_amount` | Остаточно фактично списаний ліміт |
| `remaining_amount` | Залишковий ліміт Application після списання |
| `metadata` | Публічні метадані; можуть бути порожніми |
| `service` / `credential` | Зведення пов’язаних об’єктів для зручного відображення; можуть бути порожніми, якщо пов’язаного об’єкта не існує |

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

## Обробка помилок

| HTTP | Значення | Спосіб обробки |
| - | - | - |
| 401 | Токен облікового запису відсутній або недійсний | Перевірте Account Token, не використовуйте помилково бізнес Credential |
| 403 | Немає прав на перегляд записів у запиті | Використовуйте Application, що належить поточному обліковому запису, видаліть неавторизований `user_id` |
| 5xx | Тимчасова помилка синхронізації або запиту | Збережіть умови фільтрації та повторіть спробу з експоненційною затримкою; у разі тривалої помилки надайте підтримці Application ID і час |

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

* [Переглянути записи викликів API](https://platform.acedata.cloud/documents/platform-usage-list): запит деталей сервісів звичайного типу API.
* [Отримати список Proxy сервісу](https://platform.acedata.cloud/documents/platform-service-proxies): отримати `proxy_id`.
* [Переглянути деталі заявки на сервіс](https://platform.acedata.cloud/documents/platform-application-detail): підтвердити залишковий ліміт та одиницю вимірювання.


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