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