# Historial de uso

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

Lista las tareas **completadas con éxito** de la API key que realiza la llamada, creadas dentro de una ventana de tiempo, de la más reciente a la más antigua, junto con los créditos que consumió cada una. Pensado para la conciliación automatizada: no devuelve prompts, entradas, resultados ni enlaces de descarga.

- El alcance es la API key que realiza la llamada. Para conciliar varias keys, consulte con cada una.
- Solo se listan las tareas exitosas. Las tareas fallidas, caducadas o rechazadas (normalmente reembolsadas) no se incluyen, por lo que el resultado no puede cotejarse línea por línea con sus registros de facturación.
- El filtro usa la hora de creación de la tarea. Las tareas que siguen en ejecución al consultar aún no son exitosas, así que consulte ventanas que terminaron hace al menos 30 minutos.
- Límite de tasa: 60 solicitudes por minuto por API key. Al superarlo se devuelve `429` con la cabecera `Retry-After`.

## Solicitar parámetros

### Encabezados de solicitud

| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | cadena | Sí | — | `Bearer {api_key}` |

### Parámetros de consulta

| Parámetro | Tipo | Requerido | Predeterminado | Descripción |
| :-: | :-: | :-: | :-: | :-: |
| start_time | cadena | Sí | — | Inicio de la ventana, inclusivo. RFC 3339 con desplazamiento de zona horaria, p. ej. `2026-10-01T00:00:00Z` |
| end_time | cadena | Sí | — | Fin de la ventana, exclusivo. Mismo formato; posterior a `start_time` y como máximo 31 días después |
| page_size | entero | No | `100` | Elementos por página, 1–100 |
| cursor | cadena | No | — | `next_cursor` de la página anterior; omítalo en la primera página. No cambie `start_time` ni `end_time` al paginar |

## Ejemplo de solicitud

### 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 (todas las páginas)

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

## Respuesta

### Respuesta exitosa

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

### Campos de respuesta

| Parámetro | Tipo | Descripción |
| :-: | :-: | :-: |
| code | entero | Código de estado. `0` indica éxito |
| data.items | matriz | Tareas de esta página, de la más reciente a la más antigua |
| data.items[].task_id | cadena | Identificador de la tarea |
| data.items[].type | cadena | Tipo de tarea, el mismo valor que en la consulta de tareas |
| data.items[].model_version | cadena | Versión de modelo registrada al crear; ausente si el tipo de tarea no tiene |
| data.items[].status | cadena | Siempre `success` |
| data.items[].created_at | cadena | Hora de creación, ISO 8601 en UTC |
| data.items[].completed_at | cadena | Hora de finalización, ISO 8601 en UTC; ausente si no se registró |
| data.items[].credits_consumed | number | Créditos cobrados, igual que `credits_consumed` en la consulta de tareas; `0` si no se cobró nada |
| data.has_more | booleano | Si existe otra página |
| data.next_cursor | cadena | Páselo como `cursor` para obtener la siguiente página; `null` en la última |

## Códigos de error

| Código de estado HTTP | Código de error | Descripción | Recomendación |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Parámetro no válido (hora ausente o mal formada, ventana mayor de 31 días, `page_size` o `cursor` no válidos) | Corrija el parámetro indicado en `message` |
| 429 | 1007 | Límite de tasa superado | Espere `Retry-After` segundos y reintente |
| 503 | 1008 | No disponible temporalmente | Espere `Retry-After` segundos y repita la misma solicitud |