# Cronologia utilizzo

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

Elenca le attività **completate con successo** della API key chiamante create in una finestra temporale, dalla più recente, insieme ai crediti consumati da ciascuna. Pensato per la riconciliazione automatica: non vengono restituiti prompt, input, risultati né link di download.

- L'ambito è la API key chiamante. Per riconciliare più key, interroga con ciascuna.
- Sono elencate solo le attività riuscite. Le attività fallite, scadute o rifiutate (di solito rimborsate) non sono incluse, quindi il risultato non può essere confrontato riga per riga con i tuoi dati di fatturazione.
- Il filtro usa l'ora di creazione dell'attività. Le attività ancora in esecuzione al momento della query non sono ancora riuscite, quindi interroga finestre terminate da almeno 30 minuti.
- Limite di frequenza: 60 richieste al minuto per API key. Oltre il limite viene restituito `429` con l'header `Retry-After`.

## Richiedi parametri

### Richiedi intestazioni

| Parametro | Digitare | Obbligatorio | Predefinito | Descrizione |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | stringa | Sì | — | `Bearer {api_key}` |

### Parametri di query

| Parametro | Digitare | Obbligatorio | Predefinito | Descrizione |
| :-: | :-: | :-: | :-: | :-: |
| start_time | stringa | Sì | — | Inizio della finestra, incluso. RFC 3339 con offset di fuso orario, ad es. `2026-10-01T00:00:00Z` |
| end_time | stringa | Sì | — | Fine della finestra, esclusa. Stesso formato; successiva a `start_time` e al massimo 31 giorni dopo |
| page_size | intero | No | `100` | Elementi per pagina, 1–100 |
| cursor | stringa | No | — | `next_cursor` della pagina precedente; omettere per la prima pagina. Non modificare `start_time` e `end_time` durante la paginazione |

## Richiedi esempio

### 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 (tutte le pagine)

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

## Risposta

### Risposta riuscita

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

### Campi di risposta

| Parametro | Digitare | Descrizione |
| :-: | :-: | :-: |
| code | intero | Codice di stato. `0` indica successo |
| data.items | matrice | Attività di questa pagina, dalla più recente |
| data.items[].task_id | stringa | Identificatore dell'attività |
| data.items[].type | stringa | Tipo di attività, stesso valore della query attività |
| data.items[].model_version | stringa | Versione del modello registrata alla creazione; assente se il tipo di attività non ne ha |
| data.items[].status | stringa | Sempre `success` |
| data.items[].created_at | stringa | Ora di creazione, ISO 8601 in UTC |
| data.items[].completed_at | stringa | Ora di completamento, ISO 8601 in UTC; assente se non registrata |
| data.items[].credits_consumed | number | Crediti addebitati, uguali a `credits_consumed` nella query attività; `0` se non è stato addebitato nulla |
| data.has_more | booleano | Se esiste un'altra pagina |
| data.next_cursor | stringa | Passalo come `cursor` per ottenere la pagina successiva; `null` sull'ultima pagina |

## Codici di errore

| HTTP Codice di stato | Codice errore | Descrizione | Raccomandazione |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Parametro non valido (ora mancante o malformata, finestra oltre 31 giorni, `page_size` o `cursor` non validi) | Correggi il parametro indicato in `message` |
| 429 | 1007 | Limite di frequenza superato | Attendi `Retry-After` secondi e riprova |
| 503 | 1008 | Temporaneamente non disponibile | Attendi `Retry-After` secondi e ripeti la stessa richiesta |