| name | query-alert-events |
| description | Query alert events in a Nightingale (n9e) environment. Use this when the user asks to view alerts, query active alerts, search historical alerts, view alert details, or count alert events. |
| tags | ["internal"] |
Nightingale (n9e) Query Alert Events
Query and view alert events on the Nightingale monitoring platform. Supports querying current active alerts (not yet recovered), historical alerts (recovered/not recovered), and retrieving the detailed information of a single alert.
Prerequisites
The user must provide:
- n9e address: e.g.
http://<n9e-host>:<port>
- Username/password: e.g.
<username>/<password>
- Query requirement description: e.g. "what level-1 alerts occurred in the last hour", "view active alerts", "details of alert ID 123"
If the user has not provided the information above, use the AskUserQuestion tool to ask.
Execution Steps
Step 1: Log in to obtain a Token
POST /api/n9e/auth/login
Content-Type: application/json
Body: {"username":"<username>","password":"<password>"}
Extract dat.access_token from the response, and include Authorization: Bearer <token> in all subsequent requests.
Step 2: Choose the query type based on the user's requirement
Determine which query method to use based on the user's intent:
- View active alerts (alerts currently not recovered) → use the active alerts query API
- View historical alerts (including recovered and not recovered) → use the historical alerts query API
- View alert details (the complete information of a specific alert) → use the alert details API
Decision rules:
- The user mentions "active", "current", "not recovered", "currently alerting" → active alerts
- The user mentions "historical", "past", "recovered", "has recovered" → historical alerts
- The user mentions a specific alert ID → alert details
- When not explicitly specified, query active alerts by default
Step 3: Execute the query
Method 1: Query active alerts
GET /api/n9e/alert-cur-events/list?<query_params>
Authorization: Bearer <token>
Method 2: Query historical alerts
GET /api/n9e/alert-his-events/list?<query_params>
Authorization: Bearer <token>
Method 3: Query alert details
Active alert details:
GET /api/n9e/alert-cur-event/<event_id>
Authorization: Bearer <token>
Historical alert details:
GET /api/n9e/alert-his-event/<event_id>
Authorization: Bearer <token>
Step 4: Format the output
Present the query results to the user in a readable Markdown table or list, including the key information: alert name, severity, trigger time, duration, trigger value, tags, etc.
Query Parameter Reference
Active alerts query parameters (alert-cur-events/list)
| Parameter | Type | Required | Default | Description |
|---|
severity | string | No | All | Alert severity, comma-separated, e.g. "1,2" |
query | string | No | Empty | Search keyword, matches rule name or tags |
stime | int64 | No | No limit | Start time, Unix timestamp (seconds) |
etime | int64 | No | No limit | End time, Unix timestamp (seconds) |
hours | int64 | No | 0 | Last N hours (alternative to stime/etime) |
limit | int | No | 20 | Items per page |
p | int | No | 1 | Page number |
bgid | int64 | No | 0 | Filter by business group ID |
rid | int64 | No | 0 | Filter by alert rule ID |
datasource_ids | string | No | All | Datasource IDs, comma-separated |
prods | string | No | All | Product type, comma-separated, e.g. "metric,host" |
cate | string | No | $all | Datasource category, comma-separated, e.g. "prometheus,host" |
my_groups | bool | No | false | Only show alerts from your own business groups |
event_ids | string | No | Empty | Specific event IDs, comma-separated |
Historical alerts query parameters (alert-his-events/list)
| Parameter | Type | Required | Default | Description |
|---|
severity | int | No | -1 | Alert severity, single value, -1 means all |
is_recovered | int | No | -1 | Recovery status: 0=not recovered, 1=recovered, -1=all |
query | string | No | Empty | Search keyword, matches rule name or tags |
stime | int64 | No | No limit | Start time, Unix timestamp (seconds) |
etime | int64 | No | No limit | End time, Unix timestamp (seconds) |
hours | int64 | No | 0 | Last N hours (alternative to stime/etime) |
limit | int | No | 20 | Items per page |
p | int | No | 1 | Page number |
bgid | int64 | No | 0 | Filter by business group ID |
rid | int64 | No | 0 | Filter by alert rule ID |
datasource_ids | string | No | All | Datasource IDs, comma-separated |
prods | string | No | All | Product type, comma-separated |
cate | string | No | $all | Datasource category, comma-separated |
severity alert levels
| Value | Meaning |
|---|
| 1 | Level-1 alert (Critical) |
| 2 | Level-2 alert (Warning) |
| 3 | Level-3 alert (Info) |
Time parameter usage
There are two ways to specify a time range (choose one):
Method 1: Use the hours parameter (recommended, simpler)
hours=1 → last 1 hourhours=6 → last 6 hourshours=24 → last 24 hourshours=168 → last 7 days
Method 2: Use the stime + etime parameters (precise control)
- Both are Unix timestamps (seconds)
- When only
stime is passed, etime is automatically set to the current time + 24 hours
Response Data Structure
List response
{
"dat": {
"total": 42,
"list": [<alert event object>, ...]
}
}
Active alert event fields
{
"id": 12345,
"rule_id": 10,
"rule_name": "CPU usage too high",
"rule_note": "CPU usage exceeded 80% for 5 minutes",
"rule_prod": "metric",
"severity": 1,
"cate": "prometheus",
"cluster": "default",
"datasource_id": 1,
"group_id": 2,
"group_name": "Production environment",
"hash": "rule_10_xxxx",
"target_ident": "web-server-01",
"target_note": "Web server",
"first_trigger_time"
Additional fields for historical alert events
Historical alert events add the following on top of active alerts:
{
"is_recovered": 1,
"recover_time": 1712007200
}
| is_recovered value | Meaning |
|---|
| 0 | Not recovered (alert still triggering) |
| 1 | Recovered |
Auxiliary Query APIs
Get available event tag keys
GET /api/n9e/event-tagkeys
Authorization: Bearer <token>
Returns the list of tag keys that can be used for search filtering.
Get tag values
GET /api/n9e/event-tagvalues?key=<tag_key>
Authorization: Bearer <token>
Returns the top 20 most frequent values for the specified tag key.
Get datasources associated with alert events
GET /api/n9e/alert-cur-events-datasources
Authorization: Bearer <token>
Get the business group list (for bgid filtering)
GET /api/n9e/busi-groups
Authorization: Bearer <token>
Common Query Examples
Example 1: View all active alerts
GET /api/n9e/alert-cur-events/list?limit=50
Example 2: View level-1 alerts in the last hour
GET /api/n9e/alert-cur-events/list?severity=1&hours=1
Example 3: Search active alerts by keyword
GET /api/n9e/alert-cur-events/list?query=CPU&limit=20
Example 4: View historical alerts in the last 24 hours (recovered only)
GET /api/n9e/alert-his-events/list?hours=24&is_recovered=1&limit=50
Example 5: View active alerts for a specific business group
GET /api/n9e/alert-cur-events/list?bgid=2&limit=50
Example 6: View events triggered by a specific alert rule
GET /api/n9e/alert-cur-events/list?rid=10&limit=50
Example 7: Combined filtering (level-1 and level-2 alerts + keyword + time range)
GET /api/n9e/alert-cur-events/list?severity=1,2&query=web&hours=6&limit=30
Example 8: Get details of a single alert
GET /api/n9e/alert-cur-event/12345
Key Considerations
- Active alerts vs. historical alerts: active alerts include only the alerts currently not recovered; historical alerts include both recovered and not-recovered alerts
- The severity parameter format differs: active alerts support comma-separated multiple levels (e.g.
"1,2"), while historical alerts accept only a single value (e.g. 1)
- No time limit by default: the active alerts query has no time range limit by default; for historical alerts it is recommended to specify
hours or stime/etime to avoid returning too much data
- Pagination: use the
limit and p (page number) parameters for pagination; limit defaults to 20
- tags format: the
tags in the response is a string array in ["key=value"] format
- Time fields are all Unix timestamps (seconds):
trigger_time, first_trigger_time, recover_time, last_eval_time, etc.
- query search scope: the keyword matches both the alert rule name (
rule_name) and the tags (tags)
- Alert details URLs differ: active alerts use
/alert-cur-event/<id>, historical alerts use /alert-his-event/<id> (note the singular/plural)
- Output format: format the results into a Markdown table for the user, including key columns such as alert name, severity, trigger time, target, and trigger value
