Skip to content

docs(api-reference): daily api-review 2026-11-09 — RUM active-devices flag, On-call license window fields #1173

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
flashduty wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs(api-reference): daily api-review 2026-11-09 — RUM active-devices flag, On-call license window fields #1173

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
112 changes: 105 additions & 7 deletions api-reference/on-call.openapi.en.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17639,12 +17639,12 @@
"post": {
"operationId": "oncall-license-read-license-list",
"summary": "List On-call licenses",
"description": "List people with active fixed or temporary On-call licenses in the current account.",
"description": "List the current license window's usage and the people counted in it.",
"tags": [
"On-call/Licenses"
],
"x-mint": {
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `items` contains only people with an active fixed or temporary On-call license.\n- For temporary licenses, `updated_by`, `created_at`, and `updated_at` are `0`.",
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | None — any valid `app_key` can call this operation |\n\n## Usage\n\n- `license_cnt`, `used_cnt`, `window_start` and `window_end` describe the account's current 30-day license window; a window starts at the account's creation time.\n- `rule_effective_at` is when the window-usage rules start for this account — 2026-11-09 00:00 +08:00 for an account created on or after that date, 2027-01-01 00:00 +08:00 for an older account. Before it, `license_cnt` and `used_cnt` are informational.\n- `items` contains everyone counted in the window: fixed and temporary holders plus people revoked in it, which come back with `status: revoked`.\n- For a fixed seat, `updated_by`, `created_at` and `updated_at` come from the fixed-license record; for a temporary seat they are `0`.\n- `via` and `acquired_at` are display-only: they say how and when the seat was taken in this window, not what the person may do.",
"href": "/en/api-reference/on-call/licenses/oncall-license-read-license-list",
"metadata": {
"sidebarTitle": "List On-call licenses"
Expand Down Expand Up @@ -17673,12 +17673,23 @@
"example": {
"request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N",
"data": {
"total": 2,
"license_cnt": 6,
"used_cnt": 3,
"window_start": 1793232000,
"window_end": 1795824000,
"rule_effective": false,
"rule_effective_at": 1798732800,
"auto_grab_disabled": false,
"transferred_at": 0,
"total": 3,
"items": [
{
"person_id": 80011,
"person_name": "Yuki Zhang",
"type": "fixed",
"status": "fixed",
"via": "fixed",
"acquired_at": 1793232000,
"updated_by": 80001,
"created_at": 1719792000,
"updated_at": 1719878400
Expand All @@ -17687,6 +17698,20 @@
"person_id": 80012,
"person_name": "Alex Chen",
"type": "temporary",
"status": "active",
"via": "auto",
"acquired_at": 1794021720,
"updated_by": 0,
"created_at": 0,
"updated_at": 0
},
{
"person_id": 80013,
"person_name": "Mei Lin",
"type": "temporary",
"status": "revoked",
"via": "",
"acquired_at": 0,
"updated_by": 0,
"created_at": 0,
"updated_at": 0
Expand Down Expand Up @@ -20589,20 +20614,66 @@
"schemas": {
"LicenseListResponse": {
"type": "object",
"description": "People with active fixed or temporary On-call licenses.",
"description": "License usage of the account's current 30-day On-call window, plus the people counted in it.",
"required": [
"license_cnt",
"used_cnt",
"window_start",
"window_end",
"rule_effective",
"rule_effective_at",
"auto_grab_disabled",
"transferred_at",
"total",
"items"
],
"properties": {
"license_cnt": {
"type": "integer",
"format": "int64",
"description": "Seats purchased on the account's highest-version On-call plan. `0` when the account has no resource record yet."
},
"used_cnt": {
"type": "integer",
"format": "int64",
"description": "Seats in use in the current window: people holding a license plus people revoked in this window, who stay counted until it ends."
},
"window_start": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in seconds when the current 30-day license window started."
},
"window_end": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in seconds when the current license window ends; a window is 30 days long."
},
"rule_effective": {
"type": "boolean",
"description": "Whether the window-usage license rules already apply to this account. Before `rule_effective_at` the account keeps its earlier seat behaviour."
},
"rule_effective_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in seconds when the window-usage rules start for this account: its own creation time for an account created on or after 2026-11-09 00:00 +08:00, otherwise 2027-01-01 00:00 +08:00."
},
"auto_grab_disabled": {
"type": "boolean",
"description": "Whether automatic seat grabbing is off for the account, so only fixed or admin-assigned members hold a license."
},
"transferred_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in seconds when this window's single license reassignment was used; `0` when it has not been used."
},
"total": {
"type": "integer",
"description": "Number of people holding an active license.",
"description": "Number of people in `items`.",
"format": "int64"
},
"items": {
"type": "array",
"description": "People holding an active license.",
"description": "People counted in the current window: license holders and people revoked in it.",
"items": {
"$ref": "#/components/schemas/LicensePersonItem"
}
Expand All @@ -20611,11 +20682,14 @@
},
"LicensePersonItem": {
"type": "object",
"description": "One person with an active On-call license.",
"description": "One person counted in the current On-call license window.",
"required": [
"person_id",
"person_name",
"type",
"status",
"via",
"acquired_at",
"updated_by",
"created_at",
"updated_at"
Expand All @@ -20638,6 +20712,30 @@
],
"description": "License assignment type. `fixed` is explicitly assigned; `temporary` is held from the active license window."
},
"status": {
"type": "string",
"enum": [
"fixed",
"active",
"revoked"
],
"description": "Where the person stands in this window: `fixed` holds an explicitly assigned seat, `active` holds a temporary seat taken automatically or assigned by an admin, `revoked` had the seat taken back in this window and still counts until it ends."
},
"via": {
"type": "string",
"enum": [
"auto",
"admin",
"fixed",
""
],
"description": "How the seat was taken: `auto` from an automatic grab, `admin` from an admin assignment, `fixed` from the window being seeded with the account's fixed licenses. Empty string when the window holds no record for the person, for example after a revocation."
},
"acquired_at": {
"type": "integer",
"format": "int64",
"description": "Unix timestamp in seconds when the seat was recorded in this window. `0` when the window holds no record for the person."
},
"updated_by": {
"type": "integer",
"format": "int64",
Expand Down
112 changes: 105 additions & 7 deletions api-reference/on-call.openapi.zh.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -17639,12 +17639,12 @@
"post": {
"operationId": "oncall-license-read-license-list",
"summary": "查询 On-call 许可列表",
"description": "查询当前账户中正在使用固定或临时 On-call 许可的人员。",
"description": "查询当前许可窗口的用量，以及计入该窗口的人员。",
"tags": [
"On-call/许可管理"
],
"x-mint": {
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无——任意有效的 `app_key` 都可以调用此接口 |\n\n## 使用说明\n\n- `items` 仅包含持有固定或临时 On-call 许可的人员。\n- 对临时许可，`updated_by`、`created_at` 和 `updated_at` 均为 `0`。",
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | 无——任意有效的 `app_key` 都可以调用此接口 |\n\n## 使用说明\n\n- `license_cnt`、`used_cnt`、`window_start`、`window_end` 描述账号当前 30 天的许可窗口；窗口从账号创建时间开始计算。\n- `rule_effective_at` 是窗口用量许可规则对本账号的生效时间：2026-11-09 00:00（+08:00）及之后创建的账号为自身创建时间，更早创建的账号为 2027-01-01 00:00（+08:00）。在此之前 `license_cnt` 与 `used_cnt` 仅供参考。\n- `items` 包含计入窗口的全部人员：固定与临时持有者，以及本窗口被回收许可的人员（`status` 为 `revoked`）。\n- 固定许可的 `updated_by`、`created_at`、`updated_at` 取自固定许可记录；临时许可为 `0`。\n- `via` 与 `acquired_at` 仅用于展示：说明许可是在本窗口如何、何时被占用的，不代表人员权限。",
"href": "/zh/api-reference/on-call/licenses/oncall-license-read-license-list",
"metadata": {
"sidebarTitle": "查询 On-call 许可列表"
Expand Down Expand Up @@ -17673,12 +17673,23 @@
"example": {
"request_id": "01J0D5Y31GY2TWAHRP3Q8K4M6N",
"data": {
"total": 2,
"license_cnt": 6,
"used_cnt": 3,
"window_start": 1793232000,
"window_end": 1795824000,
"rule_effective": false,
"rule_effective_at": 1798732800,
"auto_grab_disabled": false,
"transferred_at": 0,
"total": 3,
"items": [
{
"person_id": 80011,
"person_name": "Yuki Zhang",
"type": "fixed",
"status": "fixed",
"via": "fixed",
"acquired_at": 1793232000,
"updated_by": 80001,
"created_at": 1719792000,
"updated_at": 1719878400
Expand All @@ -17687,6 +17698,20 @@
"person_id": 80012,
"person_name": "Alex Chen",
"type": "temporary",
"status": "active",
"via": "auto",
"acquired_at": 1794021720,
"updated_by": 0,
"created_at": 0,
"updated_at": 0
},
{
"person_id": 80013,
"person_name": "Mei Lin",
"type": "temporary",
"status": "revoked",
"via": "",
"acquired_at": 0,
"updated_by": 0,
"created_at": 0,
"updated_at": 0
Expand Down Expand Up @@ -20589,20 +20614,66 @@
"schemas": {
"LicenseListResponse": {
"type": "object",
"description": "当前账户中持有固定或临时 On-call 许可的人员。",
"description": "账号当前 30 天 On-call 许可窗口的用量，以及计入该窗口的人员。",
"required": [
"license_cnt",
"used_cnt",
"window_start",
"window_end",
"rule_effective",
"rule_effective_at",
"auto_grab_disabled",
"transferred_at",
"total",
"items"
],
"properties": {
"license_cnt": {
"type": "integer",
"format": "int64",
"description": "账号最高版本 On-call 套餐已购买的许可数量。账号还没有资源记录时为 `0`。"
},
"used_cnt": {
"type": "integer",
"format": "int64",
"description": "当前窗口已占用的许可数量：持有许可的人员，加上本窗口被回收、但仍计入本窗口的人员。"
},
"window_start": {
"type": "integer",
"format": "int64",
"description": "当前许可窗口的起始时间，Unix 时间戳（秒）。窗口长度为 30 天。"
},
"window_end": {
"type": "integer",
"format": "int64",
"description": "当前许可窗口的结束时间，Unix 时间戳（秒）。"
},
"rule_effective": {
"type": "boolean",
"description": "窗口用量许可规则是否已对本账号生效。在 `rule_effective_at` 之前，账号沿用原有的许可行为。"
},
"rule_effective_at": {
"type": "integer",
"format": "int64",
"description": "窗口用量许可规则对本账号的生效时间，Unix 时间戳（秒）：2026-11-09 00:00（+08:00）及之后创建的账号为自己的创建时间，更早创建的账号为 2027-01-01 00:00（+08:00）。"
},
"auto_grab_disabled": {
"type": "boolean",
"description": "账号是否已关闭自动占用许可。开启后只有固定分配或被管理员指定的人员持有许可。"
},
"transferred_at": {
"type": "integer",
"format": "int64",
"description": "本窗口唯一一次许可转移的使用时间，Unix 时间戳（秒）。未使用过为 `0`。"
},
"total": {
"type": "integer",
"description": "持有有效许可的人员数量。",
"description": "`items` 中的人员数量。",
"format": "int64"
},
"items": {
"type": "array",
"description": "持有有效许可的人员。",
"description": "计入当前窗口的人员：持有许可的人员和本窗口被回收许可的人员。",
"items": {
"$ref": "#/components/schemas/LicensePersonItem"
}
Expand All @@ -20611,11 +20682,14 @@
},
"LicensePersonItem": {
"type": "object",
"description": "一名持有有效 On-call 许可的人员。",
"description": "一名计入当前 On-call 许可窗口的人员。",
"required": [
"person_id",
"person_name",
"type",
"status",
"via",
"acquired_at",
"updated_by",
"created_at",
"updated_at"
Expand All @@ -20638,6 +20712,30 @@
],
"description": "许可分配类型。`fixed` 表示固定分配，`temporary` 表示处于有效许可窗口中的临时分配。"
},
"status": {
"type": "string",
"enum": [
"fixed",
"active",
"revoked"
],
"description": "该人员在本窗口的状态：`fixed` 持有固定分配的许可，`active` 持有自动占用或管理员指定的临时许可，`revoked` 在本窗口被回收许可但仍计入本窗口直至结束。"
},
"via": {
"type": "string",
"enum": [
"auto",
"admin",
"fixed",
""
],
"description": "许可的获得方式：`auto` 为自动占用，`admin` 为管理员指定，`fixed` 为窗口初始化时带入的固定许可。窗口中没有该人员的记录时为空字符串，例如已被回收。"
},
"acquired_at": {
"type": "integer",
"format": "int64",
"description": "该人员在本窗口占用许可的记录时间，Unix 时间戳（秒）。窗口中没有该人员的记录时为 `0`。"
},
"updated_by": {
"type": "integer",
"format": "int64",
Expand Down
Loading
Loading