> ## 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 von API-Aufrufprotokollen der AceDataCloud-Plattform

> Platform API guide - Ace Data Cloud

Fragt die Details der Geschäfts-API-Aufrufe des aktuellen Kontos der letzten 60 Tage ab, geeignet zum Abgleichen von Gebühren, zum Lokalisieren fehlgeschlagener Anfragen sowie zur Fehleranalyse nach Dienst, Application, API oder Anmeldedaten.

> Auf dieser Seite werden die eigenen Aufrufprotokolle des Kontos abgefragt. Wenn Sie nur öffentliche Aufrufstatistiken einer bestimmten API auf der gesamten Plattform anzeigen möchten, verwenden Sie bitte die [API-Aufrufstatistik](https://platform.acedata.cloud/documents/platform-api-usage).

## Vorbereitung

### 1. Kontotoken erstellen

Diese Schnittstelle gehört zur Plattformverwaltungs-API und erfordert die Verwendung eines **Account Token (Kontotokens)**:

1. Melden Sie sich bei der [AceDataCloud-Plattform](https://platform.acedata.cloud) an.
2. Öffnen Sie die [Account-Token-Konsole](https://platform.acedata.cloud/console/platform-tokens).
3. Klicken Sie auf „Erstellen“ und speichern Sie das Token sofort im Passwortmanager oder Secret Manager.

Vollständige Anweisungen finden Sie unter [AceDataCloud-Plattform-Kontotokens verwalten](https://platform.acedata.cloud/documents/platform-token). Das Kontotoken wird für `platform.acedata.cloud/api/v1/**` verwendet; für den Aufruf der Geschäftsschnittstellen von `api.acedata.cloud/**` werden API-Anmeldedaten (Credential) verwendet, die beiden können nicht gemischt verwendet werden.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

Schreiben Sie das Token nicht in Frontend-Code, Protokolle oder öffentliche Repositories; falls es offengelegt wird, löschen Sie es bitte sofort in der Konsole und erstellen Sie es neu.

### 2. Filter-IDs vorbereiten (optional)

Ohne Übergabe von Filterbedingungen können die Datensätze angezeigt werden, die das aktuelle Konto anzeigen darf. Wenn Sie den Bereich eingrenzen müssen:

* `application_id`: aus der [Liste der Dienstanträge](https://platform.acedata.cloud/documents/platform-application-list) abrufen;
* `credential_id`: aus der [Liste der API-Anmeldedaten](https://platform.acedata.cloud/documents/platform-credential-list) abrufen;
* `api_id`: aus der [API-Liste](https://platform.acedata.cloud/documents/platform-api-list) abrufen;
* `service_id`: aus der [Dienstliste](https://platform.acedata.cloud/documents/platform-service-list) abrufen.

Normale Benutzer müssen `user_id` nicht übergeben; wenn es ausdrücklich übergeben wird, muss es mit dem aktuellen Konto übereinstimmen, andernfalls wird `403` zurückgegeben. Administratoren können diesen Parameter zur kontenübergreifenden Filterung verwenden.

## Schnittstellenübersicht

| Element | Inhalt |
| - | - |
| Methode | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/` |
| Authentifizierung | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read` (`platform:read` / `platform` kann erweitert enthalten sein) |
| Paginierung | `count` + `items`, standardmäßig 10 Einträge pro Seite |

## Abfragebereich

| `perspective` | Bedeutung |
| - | - |
| `both` | Standardwert; gibt Datensätze zurück, die vom aktuellen Konto bezahlt oder tatsächlich aufgerufen wurden |
| `billing` | Gibt nur Datensätze zurück, die vom aktuellen Konto bezahlt wurden |
| `actor` | Gibt nur Datensätze zurück, die tatsächlich vom aktuellen Konto aufgerufen wurden |

## Abfrageparameter

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| - | - | - | - | - |
| `perspective` | string | Nein | `both` | `billing`, `actor` oder `both` |
| `user_id` | UUID | Nein | — | Nur Administratoren filtern nach Benutzer; wiederholte Parameter werden unterstützt |
| `service_id` | UUID | Nein | — | Nach Dienst 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 |
| `status_code` | integer | Nein | — | Nach HTTP-Statuscode filtern; wiederholte oder kommagetrennte Werte werden unterstützt |
| `created_at_from` | datetime | Nein | — | Untergrenze der Erstellungszeit, ISO 8601 |
| `created_at_to` | datetime | Nein | — | Obergrenze der Erstellungszeit, ISO 8601 |
| `limit` | integer | Nein | 10 | Anzahl der Einträge pro Seite, maximal 100 |
| `offset` | integer | Nein | 0 | Paginierungsversatz |
| `ordering` | string | Nein | `-created_at` | Absteigend nach Erstellungszeit |

Wenn die Anfragezeit mehr als 60 Tage zurückliegt, gibt die Schnittstelle einen `400`-Feldvalidierungsfehler zurück und weist darauf hin, dass vollständige Aufrufdetails nur 60 Tage aufbewahrt werden.

## Anfragebeispiele

Die letzten 100 Datensätze abfragen:

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

Nach Zeit, Application und Fehlerstatus filtern:

```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-Paginierungsbeispiel:

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

## Antwortbeispiel

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

## Schlüsselfelder

| Feld | Beschreibung |
| - | - |
| `user_id` | Das Konto, das diese Belastung trägt |
| `actor_user_id` | Das Konto, das den Aufruf tatsächlich initiiert hat; kann bei der Autorisierung anderer zur Nutzung von Anmeldedaten von `user_id` abweichen |
| `used_amount` | Die nach den ursprünglichen Regeln berechnete Nutzung für diesen Aufruf |
| `original_amount` | Die ursprüngliche Nutzung vor Anwendung des Rabatts |
| `deducted_amount` | Das letztlich tatsächlich abgezogene Kontingent |
| `remaining_amount` | Das verbleibende Kontingent der Application nach Abschluss dieser Belastung |
| `elapsed` | Die vom Server aufgezeichnete Aufrufdauer in Sekunden |
| `trace_id` | Die zur Untersuchung einer einzelnen Anfrage verwendete Tracking-Kennung |
| `metadata` | Öffentliche Metadaten; die Liste gibt keine vollständigen Anfrage- oder Antwortinhalte zurück |
| `api` / `service` / `credential` | Zusammenfassungen der verknüpften Objekte zur einfachen Anzeige; können leer sein, wenn das verknüpfte Objekt nicht mehr existiert |

Die Kontingenteinheit wird durch `service.unit` der entsprechenden Application bestimmt und sollte nicht standardmäßig als US-Dollar angesehen werden.

## Fehler und Wiederholungsversuche

| HTTP | `error` | Bedeutung | Vorgehensweise |
| - | - | - | - |
| 400 | Feldvalidierungsfehler | Der Abfragebereich liegt vor der 60-tägigen Aufbewahrungsfrist | Passen Sie die Startzeit auf innerhalb der letzten 60 Tage an |
| 401 | `not_authenticated` | Das Kontotoken fehlt oder ist ungültig | Überprüfen Sie das Account Token und verwenden Sie nicht versehentlich das geschäftliche Credential |
| 403 | `permission_denied` | Die Anfrage enthält Datensätze, für deren Anzeige keine Berechtigung besteht | Entfernen Sie nicht autorisierte Benutzerfilterbedingungen |
| 429 | `usage_query_in_progress` | Eine vollständig identische Abfrage wird noch ausgeführt | Warten Sie `Retry-After` ab und wiederholen Sie den Versuch mit Backoff |
| 503 | `usage_query_timeout` | Die Abfrage überschreitet das serverseitige Sicherheitszeitlimit | Verkleinern Sie den Zeitraum oder fügen Sie Filterbedingungen hinzu und versuchen Sie es erneut |

Für dieselbe Gruppe von Abfrageparametern wird höchstens eine laufende Anfrage beibehalten. Verwenden Sie für umfangreiche Abfragen bevorzugt Zeitfenster von einem Tag oder weniger und überlagern Sie keine identischen Anfragen in festen Intervallen.

## Nächste Schritte

* [Aufrufvolumen aggregieren](https://platform.acedata.cloud/documents/platform-usage-aggregate): Sehen Sie die nach Datum und API zusammengefasste Nutzung ein.
* [Aufrufvolumen exportieren](https://platform.acedata.cloud/documents/platform-usage-export): Laden Sie große Mengen an Details direkt als CSV herunter.
* [Proxy-Aufrufprotokolle anzeigen](https://platform.acedata.cloud/documents/platform-proxy-usage): Fragen Sie Datensätze für Dienste vom Typ Proxy ab.
* [Details zur Service-Anwendung anzeigen](https://platform.acedata.cloud/documents/platform-application-detail): Prüfen Sie Guthaben und Kontingenteinheit.
* [API-Anmeldedaten rotieren](https://platform.acedata.cloud/documents/platform-credential-rotate): Ersetzen Sie die Anmeldedaten sofort, wenn ein Verdacht auf Offenlegung besteht.


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