> ## Documentation Index
> Fetch the complete documentation index at: https://docs.coze.cn/llms.txt
> Use this file to discover all available pages before exploring further.

查询已创建的用量限额配置，包括用量限额、状态、重置周期等详细信息。
:::tip 说明
* **套餐限制**：扣子企业旗舰版。
* **角色限制**：企业超级管理员和管理员可以调用该 API。
:::
## 接口描述 {#e8c41a98}
企业超级管理员和管理员可以调用该 API 查询已创建的用量限额配置。

* 针对设备的终端用户，查询**积分用量限额**或 **AI 智能通话语音时长用量限额**。
* 针对企业内的成员、空间、组织，查询**积分用量限额**。

## 接口限制 {#ea61719a}
查询企业成员、空间、组织的积分限额时， `starttime`、`endtime` 、 `trigger_time` 字段可忽略，无参考意义。
## 基础信息 {#基础信息}
<!-- @cols-width: 180,680 -->
| | | \
|**请求方式** |GET |
|---|---|
| | | \
|**请求地址** |```Plain Text |\
| |https://api.coze.cn/v1/commerce/benefit/limitations |\
| |``` |\
| | |
| | | \
|**权限** |`listBenefitLimitation` |\
| |确保调用该接口使用的访问令牌开通了 `listBenefitLimitation` 权限，详细信息参考[鉴权方式](https://docs.coze.cn/developer_guides/authentication)。 |
| | | \
|**接口说明** |查询用量限额配置。 |


## 请求参数 {#请求参数}
### Header {#Header}
<!-- @cols-width: 144,165,551 -->
| | | | \
|**参数** |**取值** |**说明** |
|---|---|---|
| | | | \
|Authorization |Bearer *$Access_Token* |用于验证客户端身份的访问令牌。你可以在扣子编程中生成访问令牌，详细信息，参考[准备工作](https://www.coze.cn/docs/developer_guides/preparation)。 |
| | | | \
|Content-Type |application/json |用于指定解析请求正文的格式，表明请求体为 JSON 格式数据。 |

### Query {#Query}
<!-- @cols-width: 134,122,87,165,339 -->
| | | | | | \
|**参数** |**类型** |**是否必选** |**示例** |**说明** |
|---|---|---|---|---|
| | | | | | \
|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`：语音通话时长用量限额（复刻音色）。 |\
| | | | | |\
| | | | |:::tip 说明 |\
| | | | |查询企业成员、空间、组织维度的用量限额配置时，需设置为 `resource_point`。 |\
| | | | |::: |
| | | | | | \
|status |String |可选 |valid |用量限额配置的当前状态，枚举值： |\
| | | | | |\
| | | | |* `valid`：正常使用。 |\
| | | | |* `frozen`：已冻结。 |\
| | | | |* `cancel`：已取消。 |
| | | | | | \
|page_token |String |可选 |\- |翻页标识，表示下一页的起始位置。当查询结果超过 `page_size` 时，返回的 `page_token`可用于获取下一页数据。 |\
| | | | |首次请求不填或置空，后续翻页需带上上一次返回的 page_token。 |
| | | | | | \
|page_size |Integer |可选 |30 |查询结果分页展示时，此参数用于设置每页返回的数据量。取值范围为 1~200，默认为 20。 |


## 返回参数 {#返回参数}

<!-- @cols-width: 165,147,164,384 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|code |Long |0 |调用状态码。0 表示调用成功，其他值表示调用失败，你可以通过 msg 字段判断详细的错误原因。 |
| | | | | \
|msg |String |"" |状态信息。API 调用失败时可通过此字段查看详细错误信息。 |\
| | | |状态码为 0 时，msg 默认为空。 |
| | | | | \
|data |Object of [ListBenefitLimitationData](#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](#responsedetail) |\- |响应详情信息。 |

### ListBenefitLimitationData {#listbenefitlimitationdata}
<!-- @cols-width: 150,147,165,398 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|has_more |Boolean |true  |是否还有下一页。 |\
| | | | |\
| | | |* true：还有下一页。 |\
| | | |* false：没有下一页。 |
| | | | | \
|page_token |String |\- |翻页标识。 |
| | | | | \
|benefit_infos |Array of [BenefitInfo](#benefitinfo) |\- |用量额度信息列表。 |

### BenefitInfo {#benefitinfo}
<!-- @cols-width: 135,148,165,412 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|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](https://docs.coze.cn/developer_guides/create_device_quotas#Body)中的`entity_id`字段。 |
| | | | | \
|status |String |valid |用量限制规则的当前状态，枚举值： |\
| | | | |\
| | | |* `valid`：正常使用。 |\
| | | |* `frozen`：已冻结。 |\
| | | |* `cancel`：取消。 |
| | | | | \
|entity_type |String |enterprise_all_devices |用量额度的限制对象， 详细说明，请参考[Body](https://docs.coze.cn/developer_guides/create_device_quotas#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`，表示每日刷新限额。 |

### ResponseDetail {#responsedetail}
<!-- @cols-width: 100,149,166,445 -->
| | | | | \
|**参数** |**类型** |**示例** |**说明** |
|---|---|---|---|
| | | | | \
|logid |String |20241210152726467C48D89D6DB2**** |本次请求的日志 ID。如果遇到异常报错场景，且反复重试仍然报错，可以根据此`logid`及错误码联系扣子团队获取帮助。详细说明可参考[获取帮助和技术支持](https://docs.coze.cn/guides/help_and_support)。 |


## 示例 {#示例}
### 请求示例 {#请求示例}
```JSON
curl --location --request GET 'https://api.coze.cn/v1/commerce/benefit/limitations?entity_type=enterprise_all_devices&entity_id=SN12345*********&benefit_type=resource_point' \
--header 'Authorization : Bearer pat_OYDacMzM3WyOWV3P****' \
--header 'Content-Type : application/json'
```

### 返回示例 {#返回示例}
```JSON
{
  "code": 0,
  "msg": "",
  "data": {
    "has_more": true,
    "page_token": "next_page_token_123",
    "benefit_infos": [
      {
        "limit": 100,
        "status": "valid",
        "ended_at": 1804185600,
        "entity_id": "SN12345*********",
        "started_at": 1753996800,
        "active_mode": "absolute_time",
        "entity_type": "enterprise_all_devices",
        "benefit_type": "resource_point",
        "trigger_time": 1,
        "trigger_unit": "never"
      }
    ]
  },
  "detail": {
    "logid": "20241210152726467C48D89D6DB2****"
  }
}
```

## 错误码 {#错误码}
如果成功调用扣子编程的 API，返回信息中 code 字段为 0。如果状态码为其他值，则表示接口调用失败。此时 msg 字段中包含详细错误信息，你可以参考[错误码](https://docs.coze.cn/developer_guides/coze_error_codes)文档查看对应的解决方法。