> ## Documentation Index
> Fetch the complete documentation index at: https://docs.acedata.cloud/llms.txt
> Use this file to discover all available pages before exploring further.

# 取得 AceDataCloud 平台 Proxy 呼叫紀錄

> Platform 整合指南 - Ace Data Cloud

查詢目前帳戶在 Proxy 類型服務下的用量紀錄。一般 API 呼叫請使用[API 呼叫紀錄](https://platform.acedata.cloud/documents/platform-usage-list)。如果不確定服務類型，可先查看[服務詳情](https://platform.acedata.cloud/documents/platform-service-detail)中的 `type`。

## 準備工作

1. 登入 [AceDataCloud 平台](https://platform.acedata.cloud)。
2. 在 [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens)建立帳戶權杖，並立即儲存到密碼管理器或 Secret Manager。
3. 開啟 [個人資料頁](https://auth.acedata.cloud/user/profile)複製目前帳戶 UUID，並儲存為 `USER_ID`。帳戶權杖建立回應中的 `user_id` 也可使用。
4. 從[服務申請列表](https://platform.acedata.cloud/documents/platform-application-list)取得 Proxy 類型服務的 `application_id`。需要依 Proxy 端點篩選時，從[服務下的 Proxy 列表](https://platform.acedata.cloud/documents/platform-service-proxies)取得 `proxy_id`。

完整權杖說明請見[管理帳戶權杖](https://platform.acedata.cloud/documents/platform-token)。本介面使用 Account Token，不使用呼叫業務 API 的 Credential。

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
export USER_ID='你的账户 UUID'
export APPLICATION_ID='你的 Proxy Application ID'
```

## 介面概覽

| 項 | 內容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/proxies/` |
| 驗證 | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| Scope | `usage:read` |
| 分頁 | `count` + `items`，預設每頁 10 筆 |

Application 擁有者依 `application_id` 查詢時，伺服器端會先同步該 Application 的可用紀錄，再回傳列表，因此回應時間可能比一般 API usage 列表更長。被授權使用者可以讀取既有的可見紀錄，但不會觸發擁有者端同步。

## 查詢參數

| 參數 | 類型 | 必填 | 預設 | 說明 |
| - | - | - | - | - |
| `user_id` | UUID | 一般使用者必填 | — | 目前帳戶 UUID；傳入其他帳戶會回傳 `403` |
| `application_id` | UUID | 建議 | — | 依 Proxy Application 篩選；支援重複參數 |
| `proxy_id` | UUID | 否 | — | 依 Proxy 端點篩選；支援重複參數 |
| `limit` | integer | 否 | 10 | 每頁筆數，最大 100 |
| `offset` | integer | 否 | 0 | 分頁偏移量 |
| `ordering` | string | 否 | `-created_at` | 依建立時間倒序 |

目前介面不支援依模型、HTTP 狀態碼、Credential 或時間範圍直接篩選，也不支援 API usage 介面的 `perspective` 參數。不要在請求中加入這些未支援參數並假設其已生效。

## 請求範例

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/proxies/' \
  --data-urlencode "user_id=${USER_ID}" \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'limit=100' \
  --data-urlencode 'ordering=-created_at' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python 分頁範例：

```python theme={null}
import os
import requests

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/proxies/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "user_id": os.environ["USER_ID"],
        "application_id": os.environ["APPLICATION_ID"],
        "limit": 100,
    },
    timeout=60,
)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["deducted_amount"], usage["remaining_amount"])
```

## 回應範例

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": null,
      "application_id": "00000000-0000-4000-8000-000000000003",
      "proxy_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": null,
      "used_amount": null,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "metadata": null,
      "created_at": "2026-09-01T08:00:00Z",
      "updated_at": "2026-09-01T08:00:00Z",
      "service": {
        "id": "00000000-0000-4000-8000-000000000005",
        "title": "Example Proxy Service"
      },
      "credential": null
    }
  ]
}
```

## 關鍵欄位

| 欄位 | 說明 |
| - | - |
| `user_id` | 承擔本次扣費的帳戶 |
| `actor_user_id` | 實際呼叫者；舊紀錄可能為空 |
| `application_id` | 產生該紀錄的 Proxy Application |
| `proxy_id` | 對應的 Proxy 端點 |
| `credential_id` | 關聯憑證 ID；舊紀錄可能為空 |
| `used_amount` | 原始紀錄的用量；可能為空 |
| `deducted_amount` | 最終實際扣除額度 |
| `remaining_amount` | 扣費後的 Application 剩餘額度 |
| `metadata` | 公開中繼資料；可能為空 |
| `service` / `credential` | 方便顯示的關聯物件摘要；關聯物件不存在時可能為空 |

額度單位由對應 Application 的 `service.unit` 決定。

## 錯誤處理

| HTTP | 含義 | 處理方式 |
| - | - | - |
| 401 | 帳戶權杖缺失或無效 | 檢查 Account Token，不要誤用業務 Credential |
| 403 | 無權查看請求中的紀錄 | 使用目前帳戶所屬的 Application，移除未授權的 `user_id` |
| 5xx | 同步或查詢暫時失敗 | 保留篩選條件並退避重試；持續失敗時提供 Application ID 和時間給支援人員 |

## 下一步

* [查看 API 呼叫紀錄](https://platform.acedata.cloud/documents/platform-usage-list)：查詢一般 API 類型服務的明細。
* [取得服務下的 Proxy 列表](https://platform.acedata.cloud/documents/platform-service-proxies)：取得 `proxy_id`。
* [查看服務申請詳情](https://platform.acedata.cloud/documents/platform-application-detail)：確認剩餘額度與單位。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.