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