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

# Pobieranie rekordów wywołań API platformy AceDataCloud

> Platform API guide - Ace Data Cloud

Wyszukaj szczegóły wywołań biznesowego API bieżącego konta z ostatnich 60 dni, odpowiednie do weryfikacji opłat, lokalizowania nieudanych żądań oraz rozwiązywania problemów według usługi, Application, API lub poświadczeń.

> Ta strona wyszukuje własne rejestry wywołań konta. Jeśli chcesz tylko wyświetlić publiczne statystyki wywołań określonego API na całej platformie, użyj [Statystyk wywołań API](https://platform.acedata.cloud/documents/platform-api-usage).

## Przygotowanie

### 1. Utwórz token konta

Ten interfejs należy do API zarządzania platformą i wymaga użycia **Account Token (tokenu konta)**:

1. Zaloguj się na [platformę AceDataCloud](https://platform.acedata.cloud).
2. Otwórz [konsolę Account Token](https://platform.acedata.cloud/console/platform-tokens).
3. Kliknij „Utwórz” i natychmiast zapisz token w menedżerze haseł lub Secret Managerze.

Pełny opis znajdziesz w sekcji [Zarządzanie tokenami konta platformy AceDataCloud](https://platform.acedata.cloud/documents/platform-token). Token konta jest używany dla `platform.acedata.cloud/api/v1/**`; do wywoływania interfejsów biznesowych `api.acedata.cloud/**` używa się poświadczeń API (Credential) i nie można używać ich zamiennie.

```shell theme={null}
export PLATFORM_TOKEN='twój token konta'
```

Nie zapisuj tokenu w kodzie frontendu, logach ani publicznych repozytoriach; jeśli wycieknie, natychmiast usuń go i utwórz ponownie w konsoli.

### 2. Przygotuj identyfikatory filtrów (opcjonalnie)

Bez przekazywania warunków filtrowania możesz wyświetlić rekordy, do których bieżące konto ma uprawnienia dostępu. Gdy potrzebujesz zawęzić zakres:

* `application_id`: uzyskaj z [listy wniosków o usługę](https://platform.acedata.cloud/documents/platform-application-list);
* `credential_id`: uzyskaj z [listy poświadczeń API](https://platform.acedata.cloud/documents/platform-credential-list);
* `api_id`: uzyskaj z [listy API](https://platform.acedata.cloud/documents/platform-api-list);
* `service_id`: uzyskaj z [listy usług](https://platform.acedata.cloud/documents/platform-service-list).

Zwykli użytkownicy nie muszą przekazywać `user_id`; jeśli zostanie przekazany jawnie, musi być zgodny z bieżącym kontem, w przeciwnym razie zwrócone zostanie `403`. Administratorzy mogą użyć tego parametru do filtrowania między kontami.

## Przegląd interfejsu

| Pozycja | Treść |
| - | - |
| Metoda | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Uwierzytelnianie | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (może być rozszerzająco zawarte przez `platform:read` / `platform`) |
| Stronicowanie | `count` + `items`, domyślnie 10 pozycji na stronę |

## Zakres zapytania

| `perspective` | Znaczenie |
| - | - |
| `both` | Wartość domyślna; zwraca rekordy opłacane lub faktycznie wywołane przez bieżące konto |
| `billing` | Zwraca tylko rekordy opłacane przez bieżące konto |
| `actor` | Zwraca tylko rekordy faktycznie wywołane przez bieżące konto |

## Parametry zapytania

| Parametr | Typ | Wymagany | Domyślnie | Opis |
| - | - | - | - | - |
| `perspective` | string | Nie | `both` | `billing`, `actor` lub `both` |
| `user_id` | UUID | Nie | — | Tylko administratorzy filtrują według użytkownika; obsługuje powtarzane parametry |
| `service_id` | UUID | Nie | — | Filtruj według usługi; obsługuje powtarzane parametry |
| `application_id` | UUID | Nie | — | Filtruj według Application; obsługuje powtarzane parametry |
| `api_id` | UUID | Nie | — | Filtruj według API; obsługuje powtarzane parametry |
| `credential_id` | UUID | Nie | — | Filtruj według poświadczeń API; obsługuje powtarzane parametry |
| `status_code` | integer | Nie | — | Filtruj według kodu stanu HTTP; obsługuje powtarzane wartości lub wartości rozdzielone przecinkami |
| `created_at_from` | datetime | Nie | — | Dolna granica czasu utworzenia, ISO 8601 |
| `created_at_to` | datetime | Nie | — | Górna granica czasu utworzenia, ISO 8601 |
| `limit` | integer | Nie | 10 | Liczba pozycji na stronę, maksymalnie 100 |
| `offset` | integer | Nie | 0 | Przesunięcie stronicowania |
| `ordering` | string | Nie | `-created_at` | Malejąco według czasu utworzenia |

Gdy czas żądania jest wcześniejszy niż ostatnie 60 dni, interfejs zwraca błąd walidacji pola `400`, informując, że pełne szczegóły wywołań są przechowywane tylko przez 60 dni.

## Przykłady żądań

Wyszukaj ostatnie 100 rekordów:

```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}"
```

Filtruj według czasu, Application i statusu niepowodzenia:

```shell theme={null}
export APPLICATION_ID='twoje 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}"
```

Przykład stronicowania w Pythonie:

```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"])
```

## Przykład odpowiedzi

```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"}
    }
  ]
}
```

## Kluczowe pola

| Pole | Opis |
| - | - |
| `user_id` | Konto obciążone za tę opłatę |
| `actor_user_id` | Konto, które faktycznie zainicjowało wywołanie; może różnić się od `user_id`, gdy upoważniono inną osobę do używania poświadczeń |
| `used_amount` | Zużycie dla tego wywołania obliczone zgodnie z pierwotnymi zasadami |
| `original_amount` | Pierwotne zużycie przed zastosowaniem rabatu aplikacji |
| `deducted_amount` | Ostatecznie faktycznie odjęta pula |
| `remaining_amount` | Pozostała pula Application po zakończeniu tego obciążenia |
| `elapsed` | Czas trwania wywołania zarejestrowany przez serwer, w sekundach |
| `trace_id` | Identyfikator śledzenia używany podczas diagnozowania pojedynczego żądania |
| `metadata` | Publiczne metadane; lista nie zwraca pełnej treści żądania ani odpowiedzi |
| `api` / `service` / `credential` | Podsumowania powiązanych obiektów ułatwiające wyświetlanie; mogą być puste, gdy powiązany obiekt już nie istnieje |

Jednostka puli jest określana przez `service.unit` odpowiadającej Application i nie należy domyślnie traktować jej jako dolarów amerykańskich.

## Błędy i ponawianie prób

| HTTP | `error` | Znaczenie | Sposób postępowania |
| - | - | - | - |
| 400 | Błąd walidacji pola | Zakres zapytania wykracza poza 60-dniowy okres przechowywania | Dostosuj czas rozpoczęcia do ostatnich 60 dni |
| 401 | `not_authenticated` | Token konta jest brakujący lub nieprawidłowy | Sprawdź Account Token, nie używaj omyłkowo Credential biznesowego |
| 403 | `permission_denied` | Żądanie zawiera rekordy, do których nie masz uprawnień wglądu | Usuń nieautoryzowane warunki filtrowania użytkowników |
| 429 | `usage_query_in_progress` | Dokładnie takie samo zapytanie jest nadal wykonywane | Poczekaj na `Retry-After`, a następnie ponów próbę z wycofaniem |
| 503 | `usage_query_timeout` | Zapytanie przekroczyło bezpieczny limit czasu serwera | Zmniejsz zakres czasu lub dodaj warunki filtrowania, a następnie ponów próbę |

Dla tego samego zestawu parametrów zapytania utrzymuj maksymalnie jedno żądanie w toku. W przypadku zapytań o dużym zakresie w pierwszej kolejności używaj okien jednodniowych lub krótszych; nie nakładaj identycznych żądań w stałych odstępach.

## Następny krok

* [Agregowanie liczby wywołań](https://platform.acedata.cloud/documents/platform-usage-aggregate)：zobacz zużycie podsumowane według daty i API.
* [Eksportowanie liczby wywołań](https://platform.acedata.cloud/documents/platform-usage-export)：pobierz dużą liczbę szczegółów bezpośrednio jako CSV.
* [Wyświetlanie rekordów wywołań Proxy](https://platform.acedata.cloud/documents/platform-proxy-usage)：wyszukaj rekordy usług typu Proxy.
* [Wyświetlanie szczegółów wniosku o usługę](https://platform.acedata.cloud/documents/platform-application-detail)：zweryfikuj saldo i jednostkę puli.
* [Rotacja poświadczeń API](https://platform.acedata.cloud/documents/platform-credential-rotate)：natychmiast zmień poświadczenia w przypadku podejrzenia ich wycieku.


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