> ## 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 Proxy-Aufrufaufzeichnungen der AceDataCloud-Plattform

> Platform API guide - Ace Data Cloud

Abfrage der Nutzungsaufzeichnungen des aktuellen Kontos für Dienste vom Typ Proxy. Für gewöhnliche API-Aufrufe verwenden Sie bitte die [API-Aufrufaufzeichnungen](https://platform.acedata.cloud/documents/platform-usage-list). Wenn der Diensttyp nicht sicher ist, können Sie zuerst den `type` in den [Servicedetails](https://platform.acedata.cloud/documents/platform-service-detail) prüfen.

## Vorbereitungen

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 in einem Passwortmanager oder Secret Manager.
3. Öffnen Sie die [Profilseite](https://auth.acedata.cloud/user/profile), kopieren Sie die UUID des aktuellen Kontos und speichern Sie sie als `USER_ID`. Die `user_id` in der Antwort zur Erstellung des Kontotokens kann ebenfalls verwendet werden.
4. Rufen Sie aus der [Liste der Serviceanträge](https://platform.acedata.cloud/documents/platform-application-list) die `application_id` eines Dienstes vom Typ Proxy ab. Wenn eine Filterung nach Proxy-Endpunkt erforderlich ist, rufen Sie aus der [Proxy-Liste unter dem Service](https://platform.acedata.cloud/documents/platform-service-proxies) die `proxy_id` ab.

Vollständige Token-Anweisungen finden Sie unter [Kontotoken verwalten](https://platform.acedata.cloud/documents/platform-token). Diese Schnittstelle verwendet ein Account Token und nicht das Credential zum Aufrufen von Geschäfts-APIs.

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

## Schnittstellenübersicht

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

Wenn der Application-Eigentümer nach `application_id` abfragt, synchronisiert der Server zuerst die verfügbaren Aufzeichnungen dieser Application und gibt dann die Liste zurück, daher kann die Antwortzeit länger sein als bei der gewöhnlichen API-Usage-Liste. Autorisierte Benutzer können vorhandene sichtbare Aufzeichnungen lesen, lösen jedoch keine Synchronisierung auf der Eigentümerseite aus.

## Abfrageparameter

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| - | - | - | - | - |
| `user_id` | UUID | Für normale Benutzer erforderlich | — | UUID des aktuellen Kontos; andere Konten geben `403` zurück |
| `application_id` | UUID | Empfohlen | — | Filterung nach Proxy Application; unterstützt wiederholte Parameter |
| `proxy_id` | UUID | Nein | — | Filterung nach Proxy-Endpunkt; unterstützt wiederholte Parameter |
| `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 |

Die aktuelle Schnittstelle unterstützt keine direkte Filterung nach Modell, HTTP-Statuscode, Credential oder Zeitbereich und auch nicht den Parameter `perspective` der API-Usage-Schnittstelle. Fügen Sie diese nicht unterstützten Parameter nicht zur Anfrage hinzu und gehen Sie nicht davon aus, dass sie wirksam sind.

## Anfragebeispiele

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/proxies/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python-Paginierungsbeispiel:

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

## Antwortbeispiel

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

## Schlüsselfelder

| Feld | Beschreibung |
| - | - |
| `user_id` | Konto, das diese Belastung trägt |
| `actor_user_id` | Tatsächlicher Aufrufer; ältere Aufzeichnungen können leer sein |
| `application_id` | Proxy Application, die diese Aufzeichnung erzeugt hat |
| `proxy_id` | Entsprechender Proxy-Endpunkt |
| `credential_id` | Zugehörige Credential-ID; ältere Aufzeichnungen können leer sein |
| `used_amount` | Nutzung der ursprünglichen Aufzeichnung; kann leer sein |
| `deducted_amount` | Tatsächlich endgültig abgezogene Quote |
| `remaining_amount` | Verbleibende Quote der Application nach der Belastung |
| `metadata` | Öffentliche Metadaten; können leer sein |
| `service` / `credential` | Zusammenfassung zugehöriger Objekte zur Anzeige; kann leer sein, wenn das zugehörige Objekt nicht existiert |

Die Quoteneinheit wird durch `service.unit` der entsprechenden Application bestimmt.

## Fehlerbehandlung

| HTTP | Bedeutung | Vorgehensweise |
| - | - | - |
| 401 | Kontotoken fehlt oder ist ungültig | Prüfen Sie das Account Token, verwenden Sie nicht versehentlich ein Geschäfts-Credential |
| 403 | Keine Berechtigung zum Anzeigen der angeforderten Aufzeichnungen | Verwenden Sie eine Application des aktuellen Kontos und entfernen Sie nicht autorisierte `user_id` |
| 5xx | Synchronisierung oder Abfrage vorübergehend fehlgeschlagen | Behalten Sie die Filterbedingungen bei und wiederholen Sie den Versuch mit Backoff; bei anhaltendem Fehler geben Sie dem Support die Application ID und die Zeit an |

## Nächste Schritte

* [API-Aufrufaufzeichnungen anzeigen](https://platform.acedata.cloud/documents/platform-usage-list): Details gewöhnlicher Dienste vom Typ API abfragen.
* [Proxy-Liste unter einem Service abrufen](https://platform.acedata.cloud/documents/platform-service-proxies): `proxy_id` abrufen.
* [Details zum Serviceantrag anzeigen](https://platform.acedata.cloud/documents/platform-application-detail): Verbleibende Quote und Einheit bestätigen.


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