> ## 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 zagregowanych statystyk użycia wywołań API platformy AceDataCloud

> Platform API guide - Ace Data Cloud

Podsumowuje liczbę żądań i faktycznie odjętą pulę bieżącego konta według daty i API, odpowiednie do tworzenia raportów miesięcznych, wykresów trendów i analiz kosztów. Aby rozwiązywać błędy pojedynczo, użyj [listy rekordów wywołań](https://platform.acedata.cloud/documents/platform-usage-list), a gdy potrzebujesz pełnych szczegółów offline, użyj [eksportu użycia](https://platform.acedata.cloud/documents/platform-usage-export).

## Przygotowanie

1. Zaloguj się na [platformie AceDataCloud](https://platform.acedata.cloud).
2. Utwórz token konta w [konsoli Account Token](https://platform.acedata.cloud/console/platform-tokens) i natychmiast go zapisz.
3. Jeśli chcesz zawęzić zakres, pobierz odpowiedni identyfikator z [listy aplikacji usługowych](https://platform.acedata.cloud/documents/platform-application-list), [listy poświadczeń API](https://platform.acedata.cloud/documents/platform-credential-list) lub [listy API](https://platform.acedata.cloud/documents/platform-api-list).

Pełny opis tokenów znajduje się w [zarządzaniu tokenami konta](https://platform.acedata.cloud/documents/platform-token). Ten interfejs używa Account Token, a nie biznesowego Credential.

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

## Przegląd interfejsu

| Pozycja | Treść |
| - | - |
| Metoda | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Uwierzytelnianie | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` obejmują go rozszerzenie) |
| Zakres uprawnień | Dla zwykłych użytkowników jest stały i obejmuje własne płatne użycie; administratorzy mogą przekazać `user_id` |

## Parametry zapytania

| Parametr | Typ | Wymagany | Domyślnie | Opis |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Nie | Pierwszy dzień bieżącego miesiąca w wybranej strefie czasowej | Czas początkowy, zalecana nazwa parametru |
| `created_at_to` | date / datetime | Nie | Bieżący czas | Czas końcowy, zalecana nazwa parametru |
| `timezone` | string | Nie | `UTC` | Strefa czasowa IANA, np. `Asia/Shanghai`; nieprawidłowe wartości wracają do UTC |
| `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świadczenia API; obsługuje powtarzane parametry |
| `include_models` | boolean | Nie | `false` | Czy dodatkowo obliczać podsumowanie według wymiaru modelu; zwiększa koszt zapytania |
| `user_id` | UUID | Nie | Dla zwykłych użytkowników stałe: własne konto; jeśli administrator nie przekaże, wszystkie konta | Tylko administratorzy mogą określić dowolne konto |

`start_time` / `end_time` mogą nadal być używane jako aliasy kompatybilne ze starszymi klientami, nowe integracje jednolicie używają `created_at_from` / `created_at_to`. Format daty dla `created_at_to` obejmuje ten dzień kalendarzowy, czyli używa północy następnego dnia jako granicy.

## Przykłady żądań

Zapytanie o dzienne/API podsumowanie bieżącego miesiąca według czasu pekińskiego, wraz z wymiarem modeli:

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Zapytanie o tygodniowe użycie określonego Application:

```shell theme={null}
export APPLICATION_ID='twój Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Przykład Python:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## Przykład odpowiedzi

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## Pola odpowiedzi

| Pole | Opis |
| - | - |
| `items` | Grupowane według daty w wybranej strefie czasowej i `api_id`; każdy wiersz zawiera `date`, `api_id`, `amount` |
| `total` | Suma `deducted_amount` w zakresie zapytania |
| `apis` | Mapowanie API ID na skrót tytułu, ułatwiające wyświetlanie `items` |
| `requests` | Łączna liczba żądań w zakresie zapytania |
| `models` | Obliczane tylko, gdy `include_models=true`; każda pozycja zawiera `model`, `amount`, `requests` |

Jednostka puli zależy od `service.unit` powiązanego Application. Jeśli zapytanie obejmuje usługi o różnych jednostkach, najpierw wykonaj statystyki osobno według `service_id` lub `application_id`, aby uniknąć bezpośredniego porównywania lub sumowania.

Gdy czas końcowy nie jest późniejszy niż czas początkowy, interfejs zwraca kompletną pustą strukturę: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Błędy i zalecenia dotyczące wydajności

| HTTP | `error` | Sposób obsługi |
| - | - | - |
| 400 | `usage_history_expired` | Dostosuj zakres czasu do okresu po `available_from` |
| 401 | `not_authenticated` | Sprawdź Account Token, nie używaj omyłkowo biznesowego Credential |
| 403 | `permission_denied` | Zwykli użytkownicy nie mogą sprawdzać innych kont |

* Domyślnie nie włączaj `include_models`; włącz go tylko wtedy, gdy raport rzeczywiście wymaga podziału według modeli.
* W przypadku zapytań o duży zakres najpierw rozdziel je według `service_id` lub `application_id`, co pozwala zarówno uniknąć mieszania jednostek, jak i zmniejszyć koszt zapytania.
* Daty bez wywołań nie są automatycznie uzupełniane zerami; przed utworzeniem wykresu klient powinien uzupełnić oś dat.

## Następny krok

* [Wyświetl rekordy wywołań](https://platform.acedata.cloud/documents/platform-usage-list): zlokalizuj szczegóły składające się na wynik agregacji.
* [Eksportuj liczbę wywołań](https://platform.acedata.cloud/documents/platform-usage-export): pobierz pełne szczegóły CSV.
* [Wyświetl szczegóły wniosku o usługę](https://platform.acedata.cloud/documents/platform-application-detail): potwierdź saldo i jednostkę.


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