# Histórico de uso

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

Lista as tarefas **concluídas com sucesso** da API key que faz a chamada, criadas dentro de uma janela de tempo, da mais recente para a mais antiga, com os créditos consumidos por cada uma. Feito para conciliação automatizada: não retorna prompts, entradas, resultados nem links de download.

- O escopo é a API key que faz a chamada. Para conciliar várias keys, consulte com cada uma.
- Apenas tarefas bem-sucedidas são listadas. Tarefas com falha, expiradas ou rejeitadas (normalmente reembolsadas) não são incluídas, portanto o resultado não pode ser conferido linha a linha com seus registros de cobrança.
- O filtro usa a hora de criação da tarefa. Tarefas ainda em execução no momento da consulta ainda não são bem-sucedidas, então consulte janelas que terminaram há pelo menos 30 minutos.
- Limite de taxa: 60 requisições por minuto por API key. Acima do limite, retorna `429` com o cabeçalho `Retry-After`.

## Parâmetros de solicitação

### Solicitar cabeçalhos

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | cadeia | Sim | — | `Bearer {api_key}` |

### Parâmetros de consulta

| Parâmetro | Tipo | Obrigatório | Padrão | Descrição |
| :-: | :-: | :-: | :-: | :-: |
| start_time | cadeia | Sim | — | Início da janela, inclusivo. RFC 3339 com deslocamento de fuso horário, p. ex. `2026-10-01T00:00:00Z` |
| end_time | cadeia | Sim | — | Fim da janela, exclusivo. Mesmo formato; posterior a `start_time` e no máximo 31 dias depois |
| page_size | inteiro | Não | `100` | Itens por página, 1–100 |
| cursor | cadeia | Não | — | `next_cursor` da página anterior; omita na primeira página. Não altere `start_time` e `end_time` durante a paginação |

## Exemplo de solicitação

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

## Resposta

### Resposta bem sucedida

```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 resposta

| Parâmetro | Tipo | Descrição |
| :-: | :-: | :-: |
| code | inteiro | Código de status. `0` indica sucesso |
| data.items | matriz | Tarefas desta página, da mais recente para a mais antiga |
| data.items[].task_id | cadeia | Identificador da tarefa |
| data.items[].type | cadeia | Tipo de tarefa, mesmo valor da consulta de tarefas |
| data.items[].model_version | cadeia | Versão do modelo registrada na criação; ausente se o tipo de tarefa não tiver |
| data.items[].status | cadeia | Sempre `success` |
| data.items[].created_at | cadeia | Hora de criação, ISO 8601 em UTC |
| data.items[].completed_at | cadeia | Hora de conclusão, ISO 8601 em UTC; ausente se não registrada |
| data.items[].credits_consumed | number | Créditos cobrados, iguais a `credits_consumed` na consulta de tarefas; `0` se nada foi cobrado |
| data.has_more | booleano | Se existe outra página |
| data.next_cursor | cadeia | Passe como `cursor` para obter a próxima página; `null` na última página |

## Códigos de erro

| Código de status HTTP | Código de erro | Descrição | Recomendação |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Parâmetro inválido (hora ausente ou malformada, janela acima de 31 dias, `page_size` ou `cursor` inválido) | Corrija o parâmetro indicado em `message` |
| 429 | 1007 | Limite de taxa excedido | Aguarde `Retry-After` segundos e tente novamente |
| 503 | 1008 | Temporariamente indisponível | Aguarde `Retry-After` segundos e repita a mesma requisição |