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