> ## 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 связанного Credential; в старых записях может отсутствовать |
| `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.