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

依日期和 API 彙總目前帳戶的請求次數與實際扣除額度，適合製作月報、趨勢圖和成本分析。需要逐筆除錯時使用[呼叫紀錄列表](https://platform.acedata.cloud/documents/platform-usage-list)，需要完整離線明細時使用[呼叫量匯出](https://platform.acedata.cloud/documents/platform-usage-export)。

## 準備工作

1. 登入 [AceDataCloud 平台](https://platform.acedata.cloud)。
2. 在 [Account Token 控制台](https://platform.acedata.cloud/console/platform-tokens)建立帳戶權杖，並立即儲存。
3. 如需縮小範圍，從[服務申請列表](https://platform.acedata.cloud/documents/platform-application-list)、[API 憑證列表](https://platform.acedata.cloud/documents/platform-credential-list)或[API 列表](https://platform.acedata.cloud/documents/platform-api-list)取得相應 ID。

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

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

## 介面概覽

| 項目 | 內容 |
| - | - |
| 方法 | `GET` |
| URL | `https://platform.acedata.cloud/api/v1/usage/apis/aggregate/` |
| 驗證 | `Authorization: Bearer ${PLATFORM_TOKEN}` |
| OAuth Scope | `usage:read`（`platform:read` / `platform` 可展開包含） |
| 權限範圍 | 一般使用者固定為自己的付費用量；管理員可傳入 `user_id` |

## 查詢參數

| 參數 | 類型 | 必填 | 預設值 | 說明 |
| - | - | - | - | - |
| `created_at_from` | date / datetime | 否 | 所選時區的本月第一天 | 開始時間，建議參數名稱 |
| `created_at_to` | date / datetime | 否 | 目前時間 | 結束時間，建議參數名稱 |
| `timezone` | string | 否 | `UTC` | IANA 時區，例如 `Asia/Shanghai`；無效值回退 UTC |
| `service_id` | UUID | 否 | — | 依服務篩選；支援重複參數 |
| `application_id` | UUID | 否 | — | 依 Application 篩選；支援重複參數 |
| `api_id` | UUID | 否 | — | 依 API 篩選；支援重複參數 |
| `credential_id` | UUID | 否 | — | 依 API 憑證篩選；支援重複參數 |
| `include_models` | boolean | 否 | `false` | 是否額外計算模型維度彙總；會增加查詢成本 |
| `user_id` | UUID | 否 | 一般使用者固定為自己；管理員未傳入時為全部帳戶 | 僅管理員可指定任意帳戶 |

`start_time` / `end_time` 作為舊用戶端相容別名仍可使用，新串接統一使用 `created_at_from` / `created_at_to`。日期形式的 `created_at_to` 會包含該自然日，即依下一日零點作為邊界。

## 請求範例

查詢北京時間本月每日/API 彙總，並附帶模型維度：

```shell theme={null}
curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  --data-urlencode 'include_models=true' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

查詢指定 Application 的一週用量：

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

curl --get 'https://platform.acedata.cloud/api/v1/usage/apis/aggregate/' \
  --data-urlencode "application_id=${APPLICATION_ID}" \
  --data-urlencode 'created_at_from=2026-09-01' \
  --data-urlencode 'created_at_to=2026-09-07' \
  --data-urlencode 'timezone=Asia/Shanghai' \
  -H "Authorization: Bearer ${PLATFORM_TOKEN}"
```

Python 範例：

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

response = requests.get(
    "https://platform.acedata.cloud/api/v1/usage/apis/aggregate/",
    headers={"Authorization": f"Bearer {os.environ['PLATFORM_TOKEN']}"},
    params={
        "created_at_from": "2026-09-01",
        "created_at_to": "2026-09-07",
        "timezone": "Asia/Shanghai",
        "include_models": "true",
    },
    timeout=30,
)
response.raise_for_status()
data = response.json()
print("requests:", data["requests"], "deducted:", data["total"])
for row in data["items"]:
    print(row["date"], row["api_id"], row["amount"])
```

## 回應範例

```json theme={null}
{
  "items": [
    {
      "date": "2026-09-01",
      "api_id": "00000000-0000-4000-8000-000000000001",
      "amount": 12.5
    }
  ],
  "total": 12.5,
  "apis": {
    "00000000-0000-4000-8000-000000000001": {
      "title": "Example API"
    }
  },
  "requests": 42,
  "models": [
    {
      "model": "example-model",
      "amount": 12.5,
      "requests": 42
    }
  ]
}
```

## 回應欄位

| 欄位 | 說明 |
| - | - |
| `items` | 依所選時區的日期和 `api_id` 分組；每列包含 `date`、`api_id`、`amount` |
| `total` | 查詢範圍內 `deducted_amount` 的總和 |
| `apis` | API ID 到標題摘要的對應，方便顯示 `items` |
| `requests` | 查詢範圍內的請求總數 |
| `models` | 僅在 `include_models=true` 時計算；每項包含 `model`、`amount`、`requests` |

額度單位取決於相關 Application 的 `service.unit`。若查詢包含不同單位的服務，請先依 `service_id` 或 `application_id` 分開統計，避免直接比較或相加。

結束時間不大於開始時間時，介面傳回完整空結構：`items=[]`、`total=0`、`apis={}`、`requests=0`、`models=[]`。

## 錯誤與效能建議

| HTTP | `error` | 處理方式 |
| - | - | - |
| 400 | `usage_history_expired` | 將時間範圍調整至回應 `available_from` 之後 |
| 401 | `not_authenticated` | 檢查 Account Token，不要誤用業務 Credential |
| 403 | `permission_denied` | 一般使用者不能查詢其他帳戶 |

* 預設不要開啟 `include_models`；只有報表確實需要模型拆分時再啟用。
* 大範圍查詢優先依 `service_id` 或 `application_id` 分開，既避免混合單位，也降低查詢成本。
* 沒有呼叫的日期不會自動補零，繪圖前由用戶端補齊日期軸。

## 下一步

* [查看呼叫紀錄](https://platform.acedata.cloud/documents/platform-usage-list)：定位構成彙總結果的明細。
* [匯出呼叫量](https://platform.acedata.cloud/documents/platform-usage-export)：下載完整 CSV 明細。
* [查看服務申請詳情](https://platform.acedata.cloud/documents/platform-application-detail)：確認餘額與單位。


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