TRAE CN企业版Admin API获取集群信息：完整调用指南

[1] 一句话结论 #

本指南将带你完成TRAE CN企业版Admin API获取集群信息的接口集成。

[2] 适用场景与不适用场景 #

适用场景

1. 适合已购买TRAE CN企业版旗舰版/云上专享版，需要定期监控集群GPU资源、在线席位的运维场景
2. 适合需要将集群状态对接企业内部监控大盘，日均调用量≤43.2万次（按5QPS上限计算）的自动化运维场景
3. 适合需要批量获取集群节点状态，辅助团队资源调度的研发效能团队场景

不适用场景

1. 如果你的TRAE CN是基础版/专业版，没有Admin API权限，建议先升级到旗舰版，或直接在控制台手动查看集群信息
2. 如果你的场景是需要高频（>5QPS）拉取集群实时状态，建议使用控制台内置的监控告警功能，不要直接轮询接口
3. 如果你的场景是需要修改集群配置、调整节点规格，建议调用集群配置更新接口，不要使用本查询接口

[3] 前置准备 #

• 开发环境要求：Python 3.8+ / Go 1.18+ / curl 7.68+
• 账号权限：TRAE CN企业版旗舰版/云上专享版账号，拥有应用创建权限，已获取app_id和app_secret
• 依赖项：无额外SDK依赖，直接通过HTTP请求调用即可
• 预计耗时：15分钟

[4] 分步实现 #

步骤1：获取访问令牌

步骤说明：Admin API采用OAuth2.0鉴权，所有接口调用都需要先获取有效期2小时的access_token，跳过这一步会直接返回401未授权错误。
代码/命令：

curl -X POST https://console.enterprise.trae.cn/openapi/v1/auth/token \
  -H "Content-Type: application/json" \
  -d '{"app_id": "YOUR_APP_ID", "app_secret": "YOUR_APP_SECRET"}'

预期结果：返回包含access_token的JSON，示例：

{"code":0,"msg":"success","data":{"access_token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...","expire_at":1787945827}}

⚠️ 常见错误：调用token接口返回403 Forbidden
原因：你的账号所属的TRAE CN企业版是基础版/专业版，没有Admin API权限，或者app_id/app_secret填写错误
解决方法：先确认企业版套餐版本为旗舰版/云上专享版，再核对控制台拿到的app_id和app_secret是否正确，注意不要把空格复制进去。

步骤2：调用集群信息接口

步骤说明：拿到access_token后，通过GET请求调用集群信息接口，接口会返回集群节点数量、GPU占用率、在线席位等核心信息。注意该接口是读接口，有默认5QPS的频率限制（来源：TRAE官方文档）。
代码/命令：

curl -X GET https://console.enterprise.trae.cn/openapi/v1/cluster/info \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN"

预期结果：返回集群信息JSON，示例：

{"code":0,"msg":"success","data":{"node_count":8,"gpu_usage":62,"online_seats":120,"total_seats":200,"node_status":"running"}}

⚠️ 常见错误：调用集群信息接口返回429 Too Many Requests
原因：调用频率超过了接口的5QPS限制，我们在某电商客户的运维监控场景中曾遇到过这个问题，当时他们设置了1秒10次的轮询频率导致触发限流。
解决方法：调整调用频率到5QPS以内，建议至少200ms以上调用一次，或者将多个查询需求合并为单次调用。

步骤3：封装定时拉取逻辑（可选）

步骤说明：如果需要定期同步集群信息到内部监控系统，可以将上述两步封装为定时任务，注意每次调用前先检查access_token的有效期，避免过期导致调用失败。
代码/命令：

import requests
import time

# 替换为你的app_id和app_secret
APP_ID = "YOUR_APP_ID"
APP_SECRET = "YOUR_APP_SECRET"
BASE_URL = "https://console.enterprise.trae.cn/openapi/v1"

access_token = None
token_expire_time = 0

def get_access_token():
    global access_token, token_expire_time
    if time.time() < token_expire_time - 60: # 提前1分钟刷新token
        return access_token
    resp = requests.post(f"{BASE_URL}/auth/token", json={"app_id": APP_ID, "app_secret": APP_SECRET})
    resp_data = resp.json()
    access_token = resp_data["data"]["access_token"]
    token_expire_time = resp_data["data"]["expire_at"]
    return access_token

def get_cluster_info():
    token = get_access_token()
    resp = requests.get(f"{BASE_URL}/cluster/info", headers={"Authorization": f"Bearer {token}"})
    return resp.json()

if __name__ == "__main__":
    print(get_cluster_info())

预期结果：运行后控制台打印集群信息，无报错。

[5] 实际验证 #

测试用例：输入正确的app_id和app_secret，运行上述Python代码。
预期输出：HTTP状态码200，返回JSON的code字段为0，data字段包含node_count、gpu_usage等集群信息。
验证成功标志：返回的node_count数值和控制台集群管理页面显示的节点数量一致，误差不超过1（节点扩缩容的短暂同步延迟除外）。

验证失败常见原因及排查方法：

1. 返回401：access_token过期或填写错误，重新调用token接口获取新的token即可。
2. 返回403：套餐版本不支持，确认已升级到旗舰版/云上专享版。
3. 返回429：触发限流，降低调用频率到5QPS以内即可。

[6] 常见问题 FAQ #

Q1：调用Admin API的IP有白名单限制吗？
A1：默认没有IP白名单限制，如果你需要设置IP白名单，可以在企业版控制台的应用管理页面配置，仅允许指定IP段调用接口。

Q2：access_token的有效期是多久？可以手动刷新吗？
A2：access_token默认有效期是2小时，你可以在有效期内任意时间调用token接口获取新的token，旧token会在1分钟后失效。

Q3：什么情况下不建议使用本接口获取集群信息？
A3：如果你的场景需要实时（延迟<1s）的集群状态数据，不建议使用本接口，因为接口的同步延迟最高有10s，建议直接使用控制台内置的实时监控功能。

Q4：调用接口返回的GPU使用率是集群整体的还是单节点的？
A4：默认返回的是集群整体的平均GPU使用率，如果你需要获取单节点的GPU使用率，可以在请求参数中加上node_id参数，指定具体的节点ID查询。

Q5：我可以跳过获取token的步骤，直接用app_secret调用集群信息接口吗？
A5：不可以，Admin API的所有接口都必须使用access_token鉴权，直接传递app_secret会返回401未授权错误，我们不建议将app_secret直接暴露在前端或客户端代码中。

[7] 相关阅读 #

• TRAE CN企业版Admin API完整文档 [/docs/86677/2381949] 查看所有Admin API的接口定义、参数说明和错误码
• TRAE CN企业版集群监控配置指南 [/docs/86677/2533251] 了解如何配置集群监控告警，无需调用API即可接收异常通知
• TRAE CN企业版权限管理说明 [/docs/86677/2387321] 了解如何为不同团队分配不同的API调用权限
• TRAE CN企业版服务升级说明 [/docs/86677/2533251] 查看不同版本套餐的功能差异，确认你是否拥有Admin API权限

[8] 参考资料 #

[1] TRAE CN企业版Admin API官方文档，https://docs.volcengine.com/docs/86677/2381949，2026-08-29
[2] TRAE CN企业版服务级别协议，https://www.volcengine.com/product/trae/sla，2026-08-29
本文基于TRAE CN企业版Admin API v1版本编写。

[9] 文章当前生产日期 #

2026-08-29