# Historique d'utilisation

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

Liste les tâches **réussies** de la clé API appelante créées dans une fenêtre de temps, des plus récentes aux plus anciennes, avec les crédits consommés par chacune. Conçu pour le rapprochement automatisé : aucun prompt, entrée, résultat ni lien de téléchargement n'est renvoyé.

- La portée est la clé API appelante. Pour rapprocher plusieurs clés, interrogez avec chacune d'elles.
- Seules les tâches réussies sont listées. Les tâches échouées, expirées ou rejetées (généralement remboursées) n'y figurent pas : le résultat ne peut donc pas être rapproché ligne à ligne de vos relevés de facturation.
- Le filtre porte sur l'heure de création de la tâche. Les tâches encore en cours au moment de la requête ne sont pas encore réussies : interrogez des fenêtres terminées depuis au moins 30 minutes.
- Limite de débit : 60 requêtes par minute et par clé API. Au-delà, la réponse est `429` avec un en-tête `Retry-After`.

## Paramètres de la demande

### En-têtes de demande

| Paramètre | Tapez | Obligatoire | Par défaut | Descriptif |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | chaîne | Oui | — | `Bearer {api_key}` |

### Paramètres de requête

| Paramètre | Tapez | Obligatoire | Par défaut | Descriptif |
| :-: | :-: | :-: | :-: | :-: |
| start_time | chaîne | Oui | — | Début de la fenêtre, inclus. RFC 3339 avec un décalage de fuseau horaire, p. ex. `2026-10-01T00:00:00Z` |
| end_time | chaîne | Oui | — | Fin de la fenêtre, exclue. Même format ; postérieure à `start_time` et au plus 31 jours après |
| page_size | entier | Non | `100` | Éléments par page, 1–100 |
| cursor | chaîne | Non | — | `next_cursor` de la page précédente ; à omettre pour la première page. Ne modifiez pas `start_time` ni `end_time` pendant la pagination |

## Exemple de demande

### 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 (toutes les pages)

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

## Réponse

### Réponse réussie

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

### Champs de réponse

| Paramètre | Tapez | Descriptif |
| :-: | :-: | :-: |
| code | entier | Code d'état. `0` indique le succès |
| data.items | tableau | Tâches de cette page, des plus récentes aux plus anciennes |
| data.items[].task_id | chaîne | Identifiant de la tâche |
| data.items[].type | chaîne | Type de tâche, même valeur que dans la requête de tâche |
| data.items[].model_version | chaîne | Version du modèle enregistrée à la création ; absente si le type de tâche n'en a pas |
| data.items[].status | chaîne | Toujours `success` |
| data.items[].created_at | chaîne | Heure de création, ISO 8601 en UTC |
| data.items[].completed_at | chaîne | Heure de fin, ISO 8601 en UTC ; absente si non enregistrée |
| data.items[].credits_consumed | number | Crédits facturés, identiques à `credits_consumed` dans la requête de tâche ; `0` si rien n'a été facturé |
| data.has_more | booléen | Indique s'il existe une autre page |
| data.next_cursor | chaîne | À passer comme `cursor` pour obtenir la page suivante ; `null` sur la dernière page |

## Codes d'erreur

| Code d'état HTTP | Code d'erreur | Descriptif | Recommandation |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Paramètre invalide (heure absente ou mal formée, fenêtre de plus de 31 jours, `page_size` ou `cursor` invalide) | Corrigez le paramètre indiqué dans `message` |
| 429 | 1007 | Limite de débit dépassée | Attendez `Retry-After` secondes puis réessayez |
| 503 | 1008 | Temporairement indisponible | Attendez `Retry-After` secondes puis renvoyez la même requête |