# История использования

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

Возвращает **успешные** задачи вызывающего API-ключа, созданные в заданном временном окне, от новых к старым, вместе с кредитами, списанными за каждую. Предназначено для автоматической сверки: промпты, входные данные, результаты и ссылки на скачивание не возвращаются.

- Область — вызывающий API-ключ. Для сверки нескольких ключей выполняйте запрос с каждым из них.
- Возвращаются только успешные задачи. Неудачные, просроченные или отклонённые задачи (обычно с возвратом кредитов) не включаются, поэтому результат нельзя построчно сверить с данными биллинга.
- Фильтрация по времени создания задачи. Задачи, которые ещё выполняются в момент запроса, пока не успешны, поэтому запрашивайте окна, закончившиеся не менее 30 минут назад.
- Ограничение частоты: 60 запросов в минуту на API-ключ. При превышении возвращается `429` с заголовком `Retry-After`.

## Параметры запроса

### Заголовки запросов

| Параметр | Тип | Требуется | По умолчанию | Описание |
| :-: | :-: | :-: | :-: | :-: |
| Authorization | строка | Да | — | `Bearer {api_key}` |

### Параметры строки запроса

| Параметр | Тип | Требуется | По умолчанию | Описание |
| :-: | :-: | :-: | :-: | :-: |
| start_time | строка | Да | — | Начало окна, включительно. RFC 3339 со смещением часового пояса, например `2026-10-01T00:00:00Z` |
| end_time | строка | Да | — | Конец окна, не включительно. Тот же формат; позже `start_time` и не более чем через 31 день |
| page_size | целое число | Нет | `100` | Элементов на странице, 1–100 |
| cursor | строка | Нет | — | `next_cursor` предыдущей страницы; для первой страницы не передавайте. Не меняйте `start_time` и `end_time` при листании |

## Пример запроса

### 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 (все страницы)

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

## Ответ

### Успешный ответ

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

### Поля ответа

| Параметр | Тип | Описание |
| :-: | :-: | :-: |
| code | целое число | Код состояния. `0` указывает на успех. |
| data.items | массив | Задачи на этой странице, от новых к старым |
| data.items[].task_id | строка | Идентификатор задачи |
| data.items[].type | строка | Тип задачи, то же значение, что в запросе задачи |
| data.items[].model_version | строка | Версия модели, записанная при создании; отсутствует, если у типа задачи её нет |
| data.items[].status | строка | Всегда `success` |
| data.items[].created_at | строка | Время создания, ISO 8601 в UTC |
| data.items[].completed_at | строка | Время завершения, ISO 8601 в UTC; отсутствует, если не записано |
| data.items[].credits_consumed | number | Списанные кредиты, то же значение, что `credits_consumed` в запросе задачи; `0`, если ничего не списано |
| data.has_more | логическое значение | Есть ли следующая страница |
| data.next_cursor | строка | Передайте как `cursor`, чтобы получить следующую страницу; `null` на последней странице |

## Коды ошибок

| HTTP Код состояния | Код ошибки | Описание | Рекомендация |
| :-: | :-: | :-: | :-: |
| 400 | 1004 | Недопустимый параметр (время отсутствует или в неверном формате, окно больше 31 дня, неверный `page_size` или `cursor`) | Исправьте параметр, указанный в `message` |
| 429 | 1007 | Превышено ограничение частоты | Подождите `Retry-After` секунд и повторите |
| 503 | 1008 | Временно недоступно | Подождите `Retry-After` секунд и повторите тот же запрос |