# Usage History

**Base URL:** `https://openapi.tripo3d.ai/v3`

**Endpoint:** `GET /account/usage/history`

Lists the **successful** tasks of the API key in the request, created within a time window, newest first, together with the credits each task consumed. It is built for automated reconciliation: no prompts, inputs, outputs or download links are returned.
- Scope is the calling API key. To reconcile several keys, query with each key.
- Only successful tasks are listed. Failed, expired or rejected tasks (usually refunded) are not included, so the result cannot be matched line by line against your billing records.
- Filtering uses the task creation time. Tasks still running when you query are not yet successful, so query windows that ended at least 30 minutes ago.
- Rate limit: 60 requests per minute per API key. Over the limit returns `429` with a `Retry-After` header.
- Errors: invalid parameters return `400` (`code=1004`); a temporary server problem returns `503` (`code=1008`) with `Retry-After` — retry the same request.


## Request Parameters

### start_time

- **Type:** string
- **Required:** Required

Window start, inclusive. RFC 3339 with a time zone offset, e.g. `2026-10-01T00:00:00Z` or `2026-10-01T08:00:00+08:00`.
### end_time

- **Type:** string
- **Required:** Required

Window end, exclusive. Same format as start_time; must be later than start_time and at most 31 days after it.
### page_size

- **Type:** integer
- **Required:** Optional
- **Default:** `100`

Items per page, 1–100.
### cursor

- **Type:** string
- **Required:** Optional

next_cursor from the previous page. Keep start_time and end_time unchanged while paging; omit for the first page.

## Response Fields

### items

- **Type:** array
- **Required:** Required

Tasks on this page, newest first.
### items[].task_id

- **Type:** string
- **Required:** Required

Task identifier.
### items[].type

- **Type:** string
- **Required:** Required

Task type, same value as in task query.
### items[].model_version

- **Type:** string
- **Required:** Optional

Model version recorded at creation; absent when the task type has none.
### items[].status

- **Type:** string
- **Required:** Required

Always success.
### items[].created_at

- **Type:** string
- **Required:** Required

Creation time, ISO 8601 in UTC.
### items[].completed_at

- **Type:** string
- **Required:** Optional

Completion time, ISO 8601 in UTC; absent when not recorded.
### items[].credits_consumed

- **Type:** number
- **Required:** Required

Credits charged for the task, the same value as credits_consumed in task query; 0 when nothing was charged.
### has_more

- **Type:** boolean
- **Required:** Required

Whether another page exists.
### next_cursor

- **Type:** string
- **Required:** Required

Pass as cursor to fetch the next page; null on the last page.

## Request Example

### First page

```
curl -s -G \
  -H "Authorization: Bearer YOUR_API_KEY" \
  --data-urlencode "start_time=2026-10-01T00:00:00Z" \
  --data-urlencode "end_time=2026-11-01T00:00:00Z" \
  https://openapi.tripo3d.ai/v3/account/usage/history
```

### Python (all pages)

```
import time
import requests

API_KEY = "YOUR_API_KEY"
url = "https://openapi.tripo3d.ai/v3/account/usage/history"
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={"Authorization": f"Bearer {API_KEY}"})
    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}")
```


## Response Example

### Page

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