> ## 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 平台 API 呼叫記錄

> Platform 整合指南 - Ace Data Cloud

查詢目前帳戶最近 60 天的業務 API 呼叫明細，適合核對扣款、定位失敗請求，以及依服務、Application、API 或憑證排查問題。

> 本頁查詢的是帳戶自己的呼叫流水。若只想查看某個 API 在整個平台上的公開呼叫統計，請使用[API 呼叫統計](https://platform.acedata.cloud/documents/platform-api-usage)。

## 準備工作

### 1. 建立帳戶權杖

本介面屬於平台管理 API，需要使用 **Account Token（帳戶權杖）**：

1. 登入 [AceDataCloud 平台](https://platform.acedata.cloud)。
2. 開啟 [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens)。
3. 點擊「建立」，立即將權杖儲存至密碼管理器或 Secret Manager。

完整說明請見[管理 AceDataCloud 平台帳戶權杖](https://platform.acedata.cloud/documents/platform-token)。帳戶權杖用於 `platform.acedata.cloud/api/v1/**`；呼叫 `api.acedata.cloud/**` 業務介面使用的是 API 憑證（Credential），兩者不能混用。

```shell theme={null}
export PLATFORM_TOKEN='你的账户令牌'
```

不要將權杖寫入前端程式碼、日誌或公開儲存庫；如果洩漏，請立即在控制台刪除並重建。

### 2. 準備篩選 ID（可選）

不傳入篩選條件即可查看目前帳戶有權查看的記錄。需要縮小範圍時：

* `application_id`：從[服務申請清單](https://platform.acedata.cloud/documents/platform-application-list)取得；
* `credential_id`：從[API 憑證清單](https://platform.acedata.cloud/documents/platform-credential-list)取得；
* `api_id`：從[API 清單](https://platform.acedata.cloud/documents/platform-api-list)取得；
* `service_id`：從[服務清單](https://platform.acedata.cloud/documents/platform-service-list)取得。

一般使用者無需傳入 `user_id`；若明確傳入，必須與目前帳戶一致，否則回傳 `403`。管理員可使用該參數跨帳戶篩選。

## 介面概覽

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

## 查詢範圍

| `perspective` | 含義 |
| - | - |
| `both` | 預設值；回傳由目前帳戶付費或實際呼叫的記錄 |
| `billing` | 僅回傳由目前帳戶付費的記錄 |
| `actor` | 僅回傳由目前帳戶實際呼叫的記錄 |

## 查詢參數

| 參數 | 類型 | 必填 | 預設 | 說明 |
| - | - | - | - | - |
| `perspective` | string | 否 | `both` | `billing`、`actor` 或 `both` |
| `user_id` | UUID | 否 | — | 僅管理員依使用者篩選；支援重複參數 |
| `service_id` | UUID | 否 | — | 依服務篩選；支援重複參數 |
| `application_id` | UUID | 否 | — | 依 Application 篩選；支援重複參數 |
| `api_id` | UUID | 否 | — | 依 API 篩選；支援重複參數 |
| `credential_id` | UUID | 否 | — | 依 API 憑證篩選；支援重複參數 |
| `status_code` | integer | 否 | — | 依 HTTP 狀態碼篩選；支援重複或逗號分隔值 |
| `created_at_from` | datetime | 否 | — | 建立時間下界，ISO 8601 |
| `created_at_to` | datetime | 否 | — | 建立時間上界，ISO 8601 |
| `limit` | integer | 否 | 10 | 每頁筆數，最大 100 |
| `offset` | integer | 否 | 0 | 分頁偏移量 |
| `ordering` | string | 否 | `-created_at` | 依建立時間倒序 |

請求時間早於最近 60 天時，介面回傳 `400` 欄位驗證錯誤，提示完整呼叫明細僅保留 60 天。

## 請求範例

查詢最近 100 筆記錄：

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

依時間、Application 和失敗狀態篩選：

```shell theme={null}
export APPLICATION_ID='你的 Application ID'

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01T00:00:00Z' \
  --data-urlencode 'created_at_to=2026-09-02T00:00:00Z' \
  --data-urlencode 'status_code=500' \
  --data-urlencode 'limit=100' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python 分頁範例：

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

url = "https://platform.acedata.cloud/api/v1/usage/apis/"
headers = {"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"}
params = {"perspective": "both", "limit": 100, "offset": 0}

response = requests.get(url, headers=headers, params=params, timeout=30)
response.raise_for_status()
data = response.json()

for usage in data["items"]:
    print(usage["created_at"], usage["status_code"], usage["deducted_amount"], usage["trace_id"])

if params["offset"] + len(data["items"]) < data["count"]:
    params["offset"] += len(data["items"])
```

## 回應範例

```json theme={null}
{
  "count": 1,
  "items": [
    {
      "id": "00000000-0000-4000-8000-000000000001",
      "user_id": "00000000-0000-4000-8000-000000000002",
      "actor_user_id": "00000000-0000-4000-8000-000000000002",
      "application_id": "00000000-0000-4000-8000-000000000003",
      "api_id": "00000000-0000-4000-8000-000000000004",
      "credential_id": "00000000-0000-4000-8000-000000000005",
      "trace_id": "example-trace-id",
      "status_code": 200,
      "used_amount": 1.25,
      "original_amount": 1.25,
      "deducted_amount": 1.25,
      "remaining_amount": 98.75,
      "started_at": "2026-09-01T08:00:00Z",
      "finished_at": "2026-09-01T08:00:01Z",
      "elapsed": 1.0,
      "created_at": "2026-09-01T08:00:01Z",
      "updated_at": "2026-09-01T08:00:01Z",
      "metadata": {"model": "example-model"},
      "api": {"title": "Example API"},
      "service": {"id": "00000000-0000-4000-8000-000000000006", "title": "Example Service"},
      "credential": {"id": "00000000-0000-4000-8000-000000000005", "name": "Production"}
    }
  ]
}
```

## 關鍵欄位

| 欄位 | 說明 |
| - | - |
| `user_id` | 承擔本次扣費的帳戶 |
| `actor_user_id` | 實際發起呼叫的帳戶；授權他人使用憑證時可能與 `user_id` 不同 |
| `used_amount` | 本次呼叫依原規則計算的用量 |
| `original_amount` | 套用 Application 折扣前的原始用量 |
| `deducted_amount` | 最終實際扣除的額度 |
| `remaining_amount` | 本次扣費完成後的 Application 剩餘額度 |
| `elapsed` | 伺服器端記錄的呼叫耗時，單位為秒 |
| `trace_id` | 排查單次請求時使用的追蹤識別碼 |
| `metadata` | 公開中繼資料；清單不會傳回完整請求或回應內容 |
| `api` / `service` / `credential` | 便於顯示的關聯物件摘要；關聯物件已不存在時可能為空 |

額度單位由對應 Application 的 `service.unit` 決定，不應預設視為美元。

## 錯誤與重試

| HTTP | `error` | 含義 | 處理方式 |
| - | - | - | - |
| 400 | 欄位驗證錯誤 | 查詢範圍早於 60 天保留期 | 將起始時間調整至最近 60 天內 |
| 401 | `not_authenticated` | 帳戶權杖缺失或無效 | 檢查 Account Token，不要誤用業務 Credential |
| 403 | `permission_denied` | 請求包含無權檢視的記錄 | 移除未授權的使用者篩選條件 |
| 429 | `usage_query_in_progress` | 完全相同的查詢仍在執行 | 等待 `Retry-After` 後退避重試 |
| 503 | `usage_query_timeout` | 查詢超過伺服器端安全時限 | 縮小時間範圍或增加篩選條件後重試 |

同一組查詢參數最多保留一個進行中的請求。大範圍查詢優先使用一天或更小的視窗，不要以固定間隔疊加相同請求。

## 下一步

* [彙總呼叫量](https://platform.acedata.cloud/documents/platform-usage-aggregate)：檢視依日期和 API 彙總的用量。
* [匯出呼叫量](https://platform.acedata.cloud/documents/platform-usage-export)：將大量明細直接下載為 CSV。
* [檢視 Proxy 呼叫記錄](https://platform.acedata.cloud/documents/platform-proxy-usage)：查詢 Proxy 類型服務的記錄。
* [檢視服務申請詳細資料](https://platform.acedata.cloud/documents/platform-application-detail)：核對餘額和額度單位。
* [輪換 API 憑證](https://platform.acedata.cloud/documents/platform-credential-rotate)：憑證疑似洩漏時立即更換。


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