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

# Abrufen aggregierter API-Aufrufstatistiken der AceDataCloud-Plattform

> Platform API guide - Ace Data Cloud

Fasst die Anzahl der Anfragen und die tatsächlich abgezogenen Kontingente des aktuellen Kontos nach Datum und API zusammen, geeignet für die Erstellung von Monatsberichten, Trenddiagrammen und Kostenanalysen. Verwenden Sie bei der Fehlersuche für einzelne Einträge die [Liste der Aufrufaufzeichnungen](https://platform.acedata.cloud/documents/platform-usage-list), und verwenden Sie für vollständige Offline-Details den [Aufrufmengenexport](https://platform.acedata.cloud/documents/platform-usage-export).

## Vorbereitung

1. Melden Sie sich bei der [AceDataCloud-Plattform](https://platform.acedata.cloud) an.
2. Erstellen Sie in der [Account-Token-Konsole](https://platform.acedata.cloud/console/platform-tokens) ein Kontotoken und speichern Sie es sofort.
3. Um den Bereich einzugrenzen, rufen Sie die entsprechenden IDs aus der [Liste der Service-Anträge](https://platform.acedata.cloud/documents/platform-application-list), der [Liste der API-Anmeldedaten](https://platform.acedata.cloud/documents/platform-credential-list) oder der [API-Liste](https://platform.acedata.cloud/documents/platform-api-list) ab.

Eine vollständige Token-Beschreibung finden Sie unter [Kontotoken verwalten](https://platform.acedata.cloud/documents/platform-token). Diese Schnittstelle verwendet ein Account Token und keine geschäftlichen Credentials.

```shell theme={null}
export PLATFORM_TOKEN='Ihr Kontotoken'
```

## Schnittstellenübersicht

| Element | Inhalt |
| - | - |
| Methode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| Authentifizierung | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` schließt dies erweitert ein) |
| Berechtigungsbereich | Für normale Benutzer fest auf die eigenen kostenpflichtigen Nutzungsmengen beschränkt; Administratoren können `user_id` übergeben |

## Abfrageparameter

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| - | - | - | - | - |
| `created_at_from` | date / datetime | Nein | Erster Tag des aktuellen Monats in der ausgewählten Zeitzone | Startzeit, empfohlener Parametername |
| `created_at_to` | date / datetime | Nein | Aktuelle Zeit | Endzeit, empfohlener Parametername |
| `timezone` | string | Nein | `UTC` | IANA-Zeitzone, z. B. `Asia/Shanghai`; ungültige Werte fallen auf UTC zurück |
| `service_id` | UUID | Nein | — | Nach Service filtern; wiederholte Parameter werden unterstützt |
| `application_id` | UUID | Nein | — | Nach Application filtern; wiederholte Parameter werden unterstützt |
| `api_id` | UUID | Nein | — | Nach API filtern; wiederholte Parameter werden unterstützt |
| `credential_id` | UUID | Nein | — | Nach API-Anmeldedaten filtern; wiederholte Parameter werden unterstützt |
| `include_models` | boolean | Nein | `false` | Ob zusätzlich eine Zusammenfassung nach Modelldimension berechnet wird; erhöht die Abfragekosten |
| `user_id` | UUID | Nein | Für normale Benutzer fest auf sich selbst; für Administratoren ohne Angabe alle Konten | Nur Administratoren können ein beliebiges Konto angeben |

`start_time` / `end_time` können weiterhin als Kompatibilitätsaliase für alte Clients verwendet werden, neue Integrationen verwenden einheitlich `created_at_from` / `created_at_to`. Die Datumsform von `created_at_to` schließt diesen Kalendertag ein, das heißt, Mitternacht des Folgetags wird als Grenze verwendet.

## Anfragebeispiele

Fragen Sie die tägliche/API-Zusammenfassung dieses Monats in Pekinger Zeit ab, einschließlich Modelldimensionen:

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

Fragen Sie die Nutzung einer bestimmten Application für eine Woche ab:

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

Python-Beispiel:

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

## Antwortbeispiel

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

## Antwortfelder

| Feld | Beschreibung |
| - | - |
| `items` | Gruppiert nach Datum der ausgewählten Zeitzone und `api_id`; jede Zeile enthält `date`, `api_id`, `amount` |
| `total` | Summe von `deducted_amount` im Abfragebereich |
| `apis` | Zuordnung von API-ID zu Titelzusammenfassung, zur Anzeige von `items` |
| `requests` | Gesamtzahl der Anfragen im Abfragebereich |
| `models` | Wird nur bei `include_models=true` berechnet; jeder Eintrag enthält `model`, `amount`, `requests` |

Die Kontingenteinheit hängt von `service.unit` der zugehörigen Application ab. Wenn die Abfrage Services mit unterschiedlichen Einheiten enthält, führen Sie die Statistik zuerst getrennt nach `service_id` oder `application_id` aus, um direkte Vergleiche oder Additionen zu vermeiden.

Wenn die Endzeit nicht größer als die Startzeit ist, gibt die Schnittstelle eine vollständige leere Struktur zurück: `items=[]`, `total=0`, `apis={}`, `requests=0`, `models=[]`.

## Fehler- und Leistungsempfehlungen

| HTTP | `error` | Vorgehensweise |
| - | - | - |
| 400 | `usage_history_expired` | Passen Sie den Zeitraum auf nach `available_from` in der Antwort an |
| 401 | `not_authenticated` | Prüfen Sie das Account Token, verwenden Sie nicht versehentlich geschäftliche Credentials |
| 403 | `permission_denied` | Normale Benutzer können keine anderen Konten abfragen |

* Aktivieren Sie `include_models` standardmäßig nicht; aktivieren Sie es nur, wenn der Bericht tatsächlich eine Modellaufschlüsselung benötigt.
* Teilen Sie umfangreiche Abfragen bevorzugt nach `service_id` oder `application_id` auf, um sowohl gemischte Einheiten zu vermeiden als auch die Abfragekosten zu senken.
* Tage ohne Aufrufe werden nicht automatisch mit Nullen aufgefüllt; ergänzen Sie vor dem Zeichnen die Datumsachse clientseitig.

## Nächste Schritte

* [Aufrufprotokolle anzeigen](https://platform.acedata.cloud/documents/platform-usage-list): Details ermitteln, aus denen das Aggregationsergebnis besteht.
* [Aufrufvolumen exportieren](https://platform.acedata.cloud/documents/platform-usage-export): Vollständige CSV-Details herunterladen.
* [Details der Serviceanfrage anzeigen](https://platform.acedata.cloud/documents/platform-application-detail): Guthaben und Einheit bestätigen.


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