# Nutzungsverlauf

> **GET** `/v3/account/usage/history`

Listet die **erfolgreichen** Aufgaben des aufrufenden API-Schlüssels auf, die in einem Zeitfenster erstellt wurden – neueste zuerst – zusammen mit den jeweils verbrauchten Credits. Gedacht für den automatisierten Abgleich: Prompts, Eingaben, Ergebnisse und Download-Links werden nicht zurückgegeben.

- Der Umfang ist der aufrufende API-Schlüssel. Für mehrere Schlüssel fragen Sie mit jedem Schlüssel einzeln ab.
- Es werden nur erfolgreiche Aufgaben aufgeführt. Fehlgeschlagene, abgelaufene oder abgelehnte Aufgaben (in der Regel erstattet) sind nicht enthalten, daher lässt sich das Ergebnis nicht Zeile für Zeile mit Ihren Abrechnungsdaten abgleichen.
- Gefiltert wird nach dem Erstellungszeitpunkt. Aufgaben, die bei der Abfrage noch laufen, sind noch nicht erfolgreich – fragen Sie daher Zeitfenster ab, die mindestens 30 Minuten zurückliegen.
- Ratenlimit: 60 Anfragen pro Minute und API-Schlüssel. Bei Überschreitung wird `429` mit einem `Retry-After`-Header zurückgegeben.

## Anforderungsparameter

### Anforderungsheader

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | Zeichenfolge | Ja | — | `Bearer {api_key}` |

### Abfrageparameter

| Parameter | Typ | Erforderlich | Standard | Beschreibung |
| :-: | :-: | :-: | :-: | :-: |
| start_time | Zeichenfolge | Ja | — | Beginn des Zeitfensters (inklusive). RFC 3339 mit Zeitzonen-Offset, z. B. `2026-10-01T00:00:00Z` |
| end_time | Zeichenfolge | Ja | — | Ende des Zeitfensters (exklusive). Gleiches Format; später als `start_time` und höchstens 31 Tage danach |
| page_size | ganze Zahl | Nein | `100` | Einträge pro Seite, 1–100 |
| cursor | Zeichenfolge | Nein | — | `next_cursor` der vorherigen Seite; für die erste Seite weglassen. `start_time` und `end_time` beim Blättern nicht ändern |

## Beispiel anfordern

### curl

```bash
curl -G https://openapi.tripo3d.ai/v3/account/usage/history \
  -H "Authorization: Bearer {api_key}" \
  --data-urlencode "start_time=2026-10-01T00:00:00Z" \
  --data-urlencode "end_time=2026-11-01T00:00:00Z" \
  --data-urlencode "page_size=100"
```

### Python (alle Seiten)

```python
import time
import requests

url = "https://openapi.tripo3d.ai/v3/account/usage/history"
headers = {"Authorization": "Bearer {api_key}"}
params = {
    "start_time": "2026-10-01T00:00:00Z",
    "end_time": "2026-11-01T00:00:00Z",
    "page_size": 100,
}
total = 0.0
while True:
    r = requests.get(url, params=params, headers=headers)
    if r.status_code in (429, 503):
        time.sleep(int(r.headers.get("Retry-After", "5")))
        continue
    r.raise_for_status()
    data = r.json()["data"]
    for item in data["items"]:
        total += item["credits_consumed"]
    if not data["has_more"]:
        break
    params["cursor"] = data["next_cursor"]
print(f"credits consumed: {total:.2f}")
```

## Antwort

### Erfolgreiche Antwort

```json
{
  "code": 0,
  "status": "success",
  "data": {
    "items": [
      {
        "task_id": "123e4567-e89b-42d3-a456-426614174000",
        "type": "text_to_model",
        "model_version": "v3.0-20250812",
        "status": "success",
        "created_at": "2026-10-31T15:59:58.123456Z",
        "completed_at": "2026-10-31T16:01:12.654321Z",
        "credits_consumed": 30.00
      }
    ],
    "has_more": true,
    "next_cursor": "djE6MTc2MTkyNjM5ODEyMzQ1NjoxMjNlNDU2Ny1lODliLTQyZDMtYTQ1Ni00MjY2MTQxNzQwMDA"
  }
}
```

### Antwortfelder

| Parameter | Typ | Beschreibung |
| :-: | :-: | :-: |
| code | ganze Zahl | Statuscode. `0` zeigt Erfolg an |
| data.items | Array | Aufgaben dieser Seite, neueste zuerst |
| data.items[].task_id | Zeichenfolge | Aufgaben-ID |
| data.items[].type | Zeichenfolge | Aufgabentyp, wie in der Aufgabenabfrage |
| data.items[].model_version | Zeichenfolge | Bei der Erstellung erfasste Modellversion; fehlt, wenn der Aufgabentyp keine hat |
| data.items[].status | Zeichenfolge | Immer `success` |
| data.items[].created_at | Zeichenfolge | Erstellungszeit, ISO 8601 in UTC |
| data.items[].completed_at | Zeichenfolge | Abschlusszeit, ISO 8601 in UTC; fehlt, wenn nicht erfasst |
| data.items[].credits_consumed | number | Berechnete Credits, wie `credits_consumed` in der Aufgabenabfrage; `0`, wenn nichts berechnet wurde |
| data.has_more | Boolescher Wert | Ob eine weitere Seite existiert |
| data.next_cursor | Zeichenfolge | Als `cursor` übergeben, um die nächste Seite abzurufen; `null` auf der letzten Seite |

## Fehlercodes

| HTTP Statuscode | Fehlercode | Beschreibung | Empfehlung |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Ungültiger Parameter (fehlende oder fehlerhafte Zeit, Zeitfenster über 31 Tage, ungültiger `page_size` oder `cursor`) | Den in `message` genannten Parameter korrigieren |
| 429 | 1007 | Ratenlimit überschritten | `Retry-After` Sekunden warten und erneut versuchen |
| 503 | 1008 | Vorübergehend nicht verfügbar | `Retry-After` Sekunden warten und dieselbe Anfrage wiederholen |