# 用量明细查询

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

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

按 API Key 查询某个时间窗内创建、且**已成功**的任务及每个任务消耗的积分，按创建时间倒序返回。 面向自动化对账：不返回提示词、输入、产物或任何下载链接。
- 查询范围是发起请求的 API Key；需要汇总多个 Key 时请分别查询。
- 只返回成功任务；失败、过期或审核未通过的任务（通常已退回积分）不在结果中，因此不能直接与账单流水逐条对账。
- 按任务创建时间筛选。查询时仍在运行的任务尚未成功，建议只查询结束时间早于当前 30 分钟以上的时间窗。
- 限流：每个 API Key 每分钟 60 次，超出返回 `429` 并带 `Retry-After` 响应头。
- 错误：参数不合法返回 `400`（`code=1004`）；服务端临时异常返回 `503`（`code=1008`）并带 `Retry-After`，原样重试即可。


## Request Parameters

### start_time

- **Type:** string
- **Required:** 必选

时间窗起点（包含）。RFC 3339 格式且必须带时区偏移，例如 `2026-10-01T00:00:00Z` 或 `2026-10-01T08:00:00+08:00`。
### end_time

- **Type:** string
- **Required:** 必选

时间窗终点（不包含）。格式同 start_time；必须晚于 start_time，且与其相差不超过 31 天。
### page_size

- **Type:** integer
- **Required:** 可选
- **Default:** `100`

每页条数，1–100。
### cursor

- **Type:** string
- **Required:** 可选

上一页返回的 next_cursor。翻页期间 start_time 与 end_time 保持不变；首页不传。

## Response Fields

### items

- **Type:** array
- **Required:** 必选

本页任务，按创建时间倒序。
### items[].task_id

- **Type:** string
- **Required:** 必选

任务 ID。
### items[].type

- **Type:** string
- **Required:** 必选

任务类型，与任务查询返回值一致。
### items[].model_version

- **Type:** string
- **Required:** 可选

创建时记录的模型版本；该任务类型没有版本时不返回。
### items[].status

- **Type:** string
- **Required:** 必选

固定为 success。
### items[].created_at

- **Type:** string
- **Required:** 必选

创建时间，UTC 的 ISO 8601 格式。
### items[].completed_at

- **Type:** string
- **Required:** 可选

完成时间，UTC 的 ISO 8601 格式；未记录时不返回。
### items[].credits_consumed

- **Type:** number
- **Required:** 必选

该任务扣除的积分，与任务查询中的 credits_consumed 一致；未扣费为 0。
### has_more

- **Type:** boolean
- **Required:** 必选

是否还有下一页。
### next_cursor

- **Type:** string
- **Required:** 必选

作为 cursor 传入以获取下一页；最后一页为 null。

## Request Example

### 首页

```
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（翻完所有页）

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

### 分页结果

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