Skip to content

Commit fc7db36

Browse files
ysyneuysyneu
authored
Merge pull request #129 from flashcatcloud/codex/flashduty-api-review-api-20260702-031612
docs: update alert event pagination API
2 parents 4fa9199 + ab30b12 commit fc7db36

4 files changed

Lines changed: 292 additions & 40 deletions

File tree

‎api-reference/on-call.openapi.en.json‎

Lines changed: 73 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1502,7 +1502,7 @@
15021502
"On-call/Incidents"
15031503
],
15041504
"x-mint": {
1505-
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |",
1505+
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Incidents Read** (`on-call`) |\n\n## Usage\n\n- Set `include_events=true` only when you need a preview of each alert's raw events.\n- Event previews are capped at the 20 newest events per alert. Use `POST /alert/event/list` for a full paginated event history.\n- `event_cnt` still reports the total number of raw events merged into each alert.",
15061506
"href": "/en/api-reference/on-call/incidents/incident-alert-list",
15071507
"metadata": {
15081508
"sidebarTitle": "List alerts of incident"
@@ -1571,7 +1571,20 @@
15711571
"images": null,
15721572
"data_source_name": "FlashMonit",
15731573
"data_source_type": "monit.alert",
1574-
"data_source_ref_id": "a_2451002751131"
1574+
"data_source_ref_id": "a_2451002751131",
1575+
"events": [
1576+
{
1577+
"event_id": "69da451df77b1b51f40e83df",
1578+
"alert_id": "69da451df77b1b51f40e83de",
1579+
"title": "CPU usage > 90%",
1580+
"event_severity": "Critical",
1581+
"event_status": "Critical",
1582+
"event_time": 1712650000,
1583+
"labels": {
1584+
"host": "web-01"
1585+
}
1586+
}
1587+
]
15751588
}
15761589
]
15771590
}
@@ -1603,7 +1616,8 @@
16031616
"incident_id": "69da451ef77b1b51f40e83ee",
16041617
"is_active": true,
16051618
"limit": 100,
1606-
"p": 1
1619+
"p": 1,
1620+
"include_events": true
16071621
}
16081622
}
16091623
}
@@ -1999,12 +2013,12 @@
19992013
"post": {
20002014
"operationId": "alert-read-event-list",
20012015
"summary": "List events for an alert",
2002-
"description": "Return all raw events that have been ingested into a specific alert, in chronological order.",
2016+
"description": "Return raw events for an alert with cursor or page-number pagination.",
20032017
"tags": [
20042018
"On-call/Alerts"
20052019
],
20062020
"x-mint": {
2007-
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Each alert accumulates raw events from the integration. This endpoint exposes the raw event history for a given alert.",
2021+
"content": "## Restrictions\n\n| Aspect | Value |\n| ------ | ----- |\n| Rate limits | **1,000 requests/minute**; **50 requests/second** per account |\n| Permissions | **Channels Read** (`on-call`) |\n\n## Usage\n\n- Results are newest-first by default. Set `asc=true` to read events oldest-first.\n- Use `limit` with `search_after_ctx` from the previous response to fetch the next page.\n- Classic page-number pagination is also supported with `p`, but `p * limit` must stay within 10,000 records.\n- Each alert can accumulate a large raw event history; prefer cursor pagination for hot alerts.",
20082022
"href": "/en/api-reference/on-call/alerts/alert-read-event-list",
20092023
"metadata": {
20102024
"sidebarTitle": "List events for an alert"
@@ -2033,6 +2047,9 @@
20332047
"example": {
20342048
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
20352049
"data": {
2050+
"total": 57,
2051+
"has_next_page": true,
2052+
"search_after_ctx": "663a1b2c3d4e5f6789abc001",
20362053
"items": [
20372054
{
20382055
"event_id": "663a1b2c3d4e5f6789abc001",
@@ -2072,7 +2089,8 @@
20722089
"$ref": "#/components/schemas/AlertEventListRequest"
20732090
},
20742091
"example": {
2075-
"alert_id": "663a1b2c3d4e5f6789abcdef"
2092+
"alert_id": "663a1b2c3d4e5f6789abcdef",
2093+
"limit": 20
20762094
}
20772095
}
20782096
}
@@ -16249,18 +16267,63 @@
1624916267
"properties": {
1625016268
"alert_id": {
1625116269
"type": "string",
16252-
"description": "Alert ID (ObjectID hex string)."
16270+
"pattern": "^[0-9a-fA-F]{24}$",
16271+
"description": "Alert ID (MongoDB ObjectID)."
16272+
},
16273+
"asc": {
16274+
"type": "boolean",
16275+
"default": false,
16276+
"description": "When true, return events oldest-first. Defaults to newest-first."
16277+
},
16278+
"limit": {
16279+
"type": "integer",
16280+
"format": "int64",
16281+
"minimum": 0,
16282+
"maximum": 100,
16283+
"default": 20,
16284+
"description": "Page size. Defaults to 20 and cannot exceed 100."
16285+
},
16286+
"p": {
16287+
"type": "integer",
16288+
"format": "int64",
16289+
"minimum": 0,
16290+
"default": 1,
16291+
"description": "Page number starting at 1. Used when `search_after_ctx` is omitted."
16292+
},
16293+
"search_after_ctx": {
16294+
"type": "string",
16295+
"pattern": "^[0-9a-fA-F]{24}$",
16296+
"description": "Cursor returned by the previous page. When supplied, cursor pagination is used instead of page-number pagination."
1625316297
}
1625416298
}
1625516299
},
1625616300
"AlertEventListResponse": {
1625716301
"type": "object",
16302+
"required": [
16303+
"items",
16304+
"total",
16305+
"has_next_page"
16306+
],
1625816307
"properties": {
1625916308
"items": {
1626016309
"type": "array",
1626116310
"items": {
1626216311
"$ref": "#/components/schemas/AlertEventItem"
16263-
}
16312+
},
16313+
"description": "Raw alert events in the requested order."
16314+
},
16315+
"total": {
16316+
"type": "integer",
16317+
"format": "int64",
16318+
"description": "Total matching event count."
16319+
},
16320+
"has_next_page": {
16321+
"type": "boolean",
16322+
"description": "Whether another page is available."
16323+
},
16324+
"search_after_ctx": {
16325+
"type": "string",
16326+
"description": "Cursor to pass as `search_after_ctx` for the next page."
1626416327
}
1626516328
}
1626616329
},
@@ -16516,7 +16579,7 @@
1651616579
"items": {
1651716580
"$ref": "#/components/schemas/AlertEventItem"
1651816581
},
16519-
"description": "Raw alert events, populated when the caller opts in."
16582+
"description": "Raw alert event preview, populated only when requested. Capped at the 20 newest events per alert."
1652016583
},
1652116584
"event_cnt": {
1652216585
"type": "integer",
@@ -22369,7 +22432,7 @@
2236922432
},
2237022433
"include_events": {
2237122434
"type": "boolean",
22372-
"description": "When true, include raw alert events in each alert item."
22435+
"description": "When true, include at most the 20 newest raw events in each alert item as a preview."
2237322436
},
2237422437
"is_active": {
2237522438
"type": [

‎api-reference/on-call.openapi.zh.json‎

Lines changed: 73 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -1502,7 +1502,7 @@
15021502
"On-call/故障管理"
15031503
],
15041504
"x-mint": {
1505-
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |",
1505+
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **故障查看**（`on-call`） |\n\n## 使用说明\n\n- 仅在需要预览每条告警的原始事件时设置 `include_events=true`。\n- 事件预览最多返回每条告警最新的 20 条事件；完整事件历史请使用 `POST /alert/event/list` 分页查询。\n- `event_cnt` 仍表示合并到每条告警的原始事件总数。",
15061506
"href": "/zh/api-reference/on-call/incidents/incident-alert-list",
15071507
"metadata": {
15081508
"sidebarTitle": "查询故障关联告警"
@@ -1571,7 +1571,20 @@
15711571
"images": null,
15721572
"data_source_name": "FlashMonit",
15731573
"data_source_type": "monit.alert",
1574-
"data_source_ref_id": "a_2451002751131"
1574+
"data_source_ref_id": "a_2451002751131",
1575+
"events": [
1576+
{
1577+
"event_id": "69da451df77b1b51f40e83df",
1578+
"alert_id": "69da451df77b1b51f40e83de",
1579+
"title": "CPU 使用率 > 90%",
1580+
"event_severity": "Critical",
1581+
"event_status": "Critical",
1582+
"event_time": 1712650000,
1583+
"labels": {
1584+
"host": "web-01"
1585+
}
1586+
}
1587+
]
15751588
}
15761589
]
15771590
}
@@ -1603,7 +1616,8 @@
16031616
"incident_id": "69da451ef77b1b51f40e83ee",
16041617
"is_active": true,
16051618
"limit": 100,
1606-
"p": 1
1619+
"p": 1,
1620+
"include_events": true
16071621
}
16081622
}
16091623
}
@@ -1999,12 +2013,12 @@
19992013
"post": {
20002014
"operationId": "alert-read-event-list",
20012015
"summary": "查询告警事件列表",
2002-
"description": "返回特定告警收到的所有原始事件，按时间顺序排列。",
2016+
"description": "通过游标或页码分页返回指定告警的原始事件。",
20032017
"tags": [
20042018
"On-call/告警管理"
20052019
],
20062020
"x-mint": {
2007-
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 每条告警会从集成持续接收原始事件，此接口展示指定告警的原始事件历史。",
2021+
"content": "## 限制说明\n\n| 项目 | 说明 |\n| ---- | ---- |\n| 速率限制 | 每个账户 **1,000 次/分钟**；**50 次/秒** |\n| 权限要求 | **协作空间查看**（`on-call`） |\n\n## 使用说明\n\n- 默认按最新事件优先返回；设置 `asc=true` 可按最早事件优先读取。\n- 使用上次响应中的 `search_after_ctx` 搭配 `limit` 获取下一页。\n- 也支持通过 `p` 使用页码分页，但 `p * limit` 必须在 10,000 条以内。\n- 单条告警可能累积大量原始事件，热点告警建议优先使用游标分页。",
20082022
"href": "/zh/api-reference/on-call/alerts/alert-read-event-list",
20092023
"metadata": {
20102024
"sidebarTitle": "查询告警事件列表"
@@ -2033,6 +2047,9 @@
20332047
"example": {
20342048
"request_id": "01HK8XQE3Z7JM2NTFQ5YJ8P9R4",
20352049
"data": {
2050+
"total": 57,
2051+
"has_next_page": true,
2052+
"search_after_ctx": "663a1b2c3d4e5f6789abc001",
20362053
"items": [
20372054
{
20382055
"event_id": "663a1b2c3d4e5f6789abc001",
@@ -2072,7 +2089,8 @@
20722089
"$ref": "#/components/schemas/AlertEventListRequest"
20732090
},
20742091
"example": {
2075-
"alert_id": "663a1b2c3d4e5f6789abcdef"
2092+
"alert_id": "663a1b2c3d4e5f6789abcdef",
2093+
"limit": 20
20762094
}
20772095
}
20782096
}
@@ -16241,18 +16259,63 @@
1624116259
"properties": {
1624216260
"alert_id": {
1624316261
"type": "string",
16244-
"description": "告警 ID（ObjectID 十六进制字符串）。"
16262+
"pattern": "^[0-9a-fA-F]{24}$",
16263+
"description": "告警 ID（MongoDB ObjectID）。"
16264+
},
16265+
"asc": {
16266+
"type": "boolean",
16267+
"default": false,
16268+
"description": "为 true 时按最早事件优先返回；默认按最新事件优先返回。"
16269+
},
16270+
"limit": {
16271+
"type": "integer",
16272+
"format": "int64",
16273+
"minimum": 0,
16274+
"maximum": 100,
16275+
"default": 20,
16276+
"description": "分页大小，默认 20，最大 100。"
16277+
},
16278+
"p": {
16279+
"type": "integer",
16280+
"format": "int64",
16281+
"minimum": 0,
16282+
"default": 1,
16283+
"description": "页码，从 1 开始；未传 `search_after_ctx` 时生效。"
16284+
},
16285+
"search_after_ctx": {
16286+
"type": "string",
16287+
"pattern": "^[0-9a-fA-F]{24}$",
16288+
"description": "上一页响应返回的游标；传入后使用游标分页而非页码分页。"
1624516289
}
1624616290
}
1624716291
},
1624816292
"AlertEventListResponse": {
1624916293
"type": "object",
16294+
"required": [
16295+
"items",
16296+
"total",
16297+
"has_next_page"
16298+
],
1625016299
"properties": {
1625116300
"items": {
1625216301
"type": "array",
1625316302
"items": {
1625416303
"$ref": "#/components/schemas/AlertEventItem"
16255-
}
16304+
},
16305+
"description": "按请求顺序返回的原始告警事件。"
16306+
},
16307+
"total": {
16308+
"type": "integer",
16309+
"format": "int64",
16310+
"description": "命中的事件总数。"
16311+
},
16312+
"has_next_page": {
16313+
"type": "boolean",
16314+
"description": "是否还有下一页。"
16315+
},
16316+
"search_after_ctx": {
16317+
"type": "string",
16318+
"description": "下一页请求可作为 `search_after_ctx` 传入的游标。"
1625616319
}
1625716320
}
1625816321
},
@@ -16508,7 +16571,7 @@
1650816571
"items": {
1650916572
"$ref": "#/components/schemas/AlertEventItem"
1651016573
},
16511-
"description": "原始告警事件，调用方显式请求时返回。"
16574+
"description": "原始告警事件预览，仅在调用方请求时返回；每条告警最多返回最新 20 条。"
1651216575
},
1651316576
"event_cnt": {
1651416577
"type": "integer",
@@ -22360,7 +22423,7 @@
2236022423
},
2236122424
"include_events": {
2236222425
"type": "boolean",
22363-
"description": "true 时返回每条告警下的原始事件。"
22426+
"description": "为 true 时，在每条告警中最多返回最新 20 条原始事件作为预览。"
2236422427
},
2236522428
"is_active": {
2236622429
"type": [

0 commit comments

Comments
 (0)