查询用量限额配置

请求地址

权限

listBenefitLimitation
确保调用该接口使用的访问令牌开通了 listBenefitLimitation 权限，详细信息参考鉴权方式。

接口说明

查询用量限额配置。

Authorization

Bearer $Access_Token

用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考准备工作。

Content-Type

application/json

用于指定解析请求正文的格式，表明请求体为 JSON 格式数据。

entity_type

String

必选

enterprise_all_devices

用量限额对象，枚举值：

• 终端用户维度的可选值如下：
  • enterprise_all_devices：所有已上报的设备。
  • enterprise_all_custom_consumers：所有已上报的自定义实体。
  • single_device：单个设备。
  • single_custom_consumer：单个自定义实体。
• 企业成员、空间、组织维度的可选值如下：
  • coze_user_id：单个企业成员。
  • coze_role：单类企业角色。
  • coze_workspace：企业工作空间。
  • coze_organization：企业组织。

entity_id

String

可选

SN12345*********

用量限额对象的 ID。

• entity_type 为 single_device 时，设置 entity_id 为设备 ID。
• entity_type 为 single_custom_consumer 时，设置 entity_id为自定义实体 ID。
• entity_type 为 enterprise_all_devices、enterprise_all_custom_consumers 时，无需设置 entity_id。
• entity_type 为 coze_workspace 时，设置 entity_id 为空间 ID。
• entity_type 为 coze_organization 时，设置 entity_id 为组织 ID。
• entity_type 为 coze_user_id 时，设置 entity_id 为扣子用户 ID。
• entity_type 为 coze_role 时，设置 entity_id 为角色类型，枚举值：
  • EnterpriseGuest：访客
  • EnterpriseMember：成员
  • EnterpriseAdmin：管理员

benefit_type

String

必选

resource_point

用量限额类型，枚举值：

• resource_point：积分用量限额。
• voice_unified_duration_system：语音通话时长用量限额（系统音色）。
• voice_unified_duration_custom：语音通话时长用量限额（复刻音色）。

status

String

可选

valid

用量限额配置的当前状态，枚举值：

• valid：正常使用。
• frozen：已冻结。
• cancel：已取消。

page_token

String

可选

-

翻页标识，表示下一页的起始位置。当查询结果超过 page_size 时，返回的 page_token可用于获取下一页数据。
首次请求不填或置空，后续翻页需带上上一次返回的 page_token。

page_size

Integer

可选

30

查询结果分页展示时，此参数用于设置每页返回的数据量。取值范围为 1~200，默认为 20。

code

Long

0

调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。

msg

String

“”

状态信息。API 调用失败时可通过此字段查看详细错误信息。
状态码为 0 时，msg 默认为空。

data

Object of ListBenefitLimitationData

{ “benefit_id”: 123***, “benefit_type”: “resource_point”, “active_mode”: “absolute_time”, “started_at”: 1741708800, “ended_at”: 1741708800, “limit”: 100, “status”: “valid” }

接口调用成功时，返回的详细数据信息。

detail

Object of ResponseDetail

-

响应详情信息。

has_more

Boolean

true

是否还有下一页。

• true：还有下一页。
• false：没有下一页。

page_token

String

-

翻页标识。

benefit_infos

Array of BenefitInfo

-

用量额度信息列表。

limit

Long

100

用量限额的具体数值。

• benefit_type 为 resource_point 时，单位为积分。
• benefit_type 为 voice_unified_duration_system或voice_unified_duration_custom 时，单位为秒。

benefit_type

String

resource_point

用量限额类型，枚举值：

• resource_point：积分用量限额。
• voice_unified_duration_system：语音通话时长用量限额（系统音色）。
• voice_unified_duration_custom：语音通话时长用量限额（复刻音色）。

active_mode

String

absolute_time

激活模式，当前仅支持设置为 absolute_time ，即绝对时间。
该模式下，权益生效时间由 started_at 和 ended_at 两个时间确定。

started_at

Long

1753996800

用量限额配置的生效起始时间，Unixtime 时间戳格式，单位为秒。

ended_at

Long

253402300799

用量限额配置的生效截止时间，Unixtime 时间戳格式，单位为秒。过期后，该限额配置会失效。

entity_id

String

SN12345*********

用量限额对象的 ID。 详细说明，请参考Body中的entity_id字段。

status

String

valid

用量限制规则的当前状态，枚举值：

• valid：正常使用。
• frozen：已冻结。
• cancel：取消。

entity_type

String

enterprise_all_devices

用量额度的限制对象， 详细说明，请参考Body中的entity_type字段。

trigger_unit

String

day

用量限额的重置周期单位，系统将根据指定时间间隔重置限额。枚举值：

• never：不重置额度，适用于设置累计可用额度上限。
• minute：以分钟为周期重置额度。
• hour：以小时为周期重置额度。
• day：以天为周期重置额度。

trigger_time

Long

1

用量限额的重置频率。

• 当 trigger_unit 为 never 时，trigger_time 的值为 1，无实际意义。
• 当 trigger_unit 为 minute、hour 或 day 时，trigger_time 表示具体的刷新频率，例如：trigger_unit=day 且 trigger_time = 1，表示每日刷新限额。

logid

String

20241210152726467C48D89D6DB2****

本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此logid及错误码联系扣子团队获取帮助。详细说明可参考获取帮助和技术支持。