Version: 1.3

Querying alerts

Overview

ToBeAlert provides several endpoints to retrieve alerts, whether by ID, by view, by service, or as a full paginated list. All endpoints require a valid API key.

Authorization: Key YOUR_API_KEY_HERE

Get a single alert

GET /api/alert/<alert_id>
Authorization: Key YOUR_API_KEY

Returns the full details of a single alert by its ID.

Example

Get a single alert by its ID

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/alert/ALERT_ID" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/alert/ALERT_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "total": 1,
  "alert": {
    "id": "abc123",
    "resource": "web-01.example.com",
    "event": "ServerDown",
    "environment": "production",
    "severity": "critical",
    "status": "open",
    "text": "Server is not responding",
    "service": ["web-service"],
    "group": "infrastructure",
    "tags": ["linux", "production"],
    "attributes": {},
    "origin": "nagios",
    "createTime": "2025-04-15T10:00:00Z",
    "lastReceiveTime": "2025-04-15T10:30:00Z",
    "duplicateCount": 3,
    "trendIndication": "moreSevere",
    "causeId": null,
    "suppressed": false,
    "effectCount": 2,
    "isEffect": false,
    "isCause": true,
    "resourceParent": "web-cluster-01",
    "resourceParents": ["web-cluster-01"],
    "resourceChildren": [],
    "resourceAncestors": [
      { "resource": "web-cluster-01", "depth": 1 },
      { "resource": "dc-madrid", "depth": 2 }
    ]
  }
}

Cause and effect fields

Every alert object includes the cause/effect link fields (see Sending alerts — Cause and effect):

Field	Type	Meaning
`causeId`	String or `null`	ID of the alert this one is an effect of
`suppressed`	Boolean	Dimmed and grouped under its cause on the dashboard
`effectCount`	Integer	Number of effects that point to this alert
`isEffect`	Boolean	`true` when `causeId` is set
`isCause`	Boolean	`true` when `effectCount` is greater than `0`

effectCount, isEffect, and isCause are computed and read-only. All five are available as columns in the Web UI and as alerts.cause_id, alerts.suppressed, alerts.effect_count, alerts.is_effect, and alerts.is_cause in view SQL queries.

Resource relation fields

resourceParent is a stored alert column (see Sending alerts — Resource relations). The single-alert response adds three read-only fields computed from the resource graph for the alert's environment and resource:

Field	Type	Meaning
`resourceParent`	String or `null`	The parent declared by the alert payload (or set by a policy). Filterable and sortable like any text column
`resourceParents`	Array of strings	Every parent the graph knows for this resource, from any source. The first one is the primary parent; the alert's own `resourceParent` is always included
`resourceChildren`	Array of strings	Direct children of the resource in the graph
`resourceAncestors`	Array of `{resource, depth}`	Parents, grandparents, and so on, up to depth 10. `depth` 1 is a direct parent

resourceParents, resourceChildren, and resourceAncestors are returned only by GET /api/alert/<alert_id>, not by the list endpoints. If the graph cannot be read, the three fields come back as empty arrays and the alert is still returned. For the full graph of a resource (relation ids, sources, descendants), use GET /api/resources/graph.

Errors

Code	Reason
`404`	Alert not found

List all alerts

GET /api/alerts
Authorization: Key YOUR_API_KEY

Returns a paginated list of all alerts across all views. Requires the requesting user to belong to the all_events group.

Query parameters

Filtering

Parameter	Type	Description	Example
`id`	String	Filter by alert ID	`?id=abc123`
`resource`	String	Filter by resource name	`?resource=web-01`
`resourceParent`	String	Filter by parent resource (also in TQL: `resourceParent:eq:web-cluster`, in views, and in the filter builder)	`?resourceParent=web-cluster`
`event`	String	Filter by event type	`?event=ServerDown`
`environment`	String	Filter by environment	`?environment=production`
`severity`	String	Filter by severity level	`?severity=critical`
`status`	String	Filter by alert status	`?status=open`
`service`	String	Filter by service (array match)	`?service=web-service`
`sourceId`	String	Filter by source application	`?sourceId=nagios`
`group`	String	Filter by group	`?group=infrastructure`
`origin`	String	Filter by origin	`?origin=nagios`
`type`	String	Filter by alert type	`?type=exceptionAlert`
`tags`	String	Filter by tag	`?tags=linux`
`text`	String	Filter by description text	`?text=not+responding`
`value`	String	Filter by metric value (exact text)	`?value=503`
`trendIndication`	String	Filter by trend	`?trendIndication=moreSevere`
`repeat`	Boolean	Filter repeating alerts	`?repeat=true`
`duplicateCount`	Integer	Filter by duplicate count	`?duplicateCount=5`
`from-date`	ISO 8601	Alerts updated after this date	`?from-date=2025-04-01T00:00:00Z`
`to-date`	ISO 8601	Alerts updated before this date	`?to-date=2025-04-15T23:59:59Z`
`attributes.<key>`	String	Filter by attribute value	`?attributes.region=us-west-2`

Sorting

Use the sort-by parameter. Prefix with - to sort descending.

Example	Description
`?sort-by=severity`	Sort by severity ascending
`?sort-by=-lastReceiveTime`	Sort by last received, newest first
`?sort-by=-createTime`	Sort by creation time, newest first
`?sort-by=openFor`	Longest-open alerts first (`openFor` = now − `createTime`); `-openFor` for the newest first
`?sort-by=silentFor`	Alerts not received for the longest time first (`silentFor` = now − `lastReceiveTime`)

Supported sort fields: id, resource, resourceParent, event, environment, severity, status, group, origin, createTime, lastReceiveTime, updateTime, duplicateCount, trendIndication, value, tags, and the computed durations openFor and silentFor.

In TQL (dashboard search, views, filter builder) openFor and silentFor are also filter columns (openFor:gt:1d), date columns accept relative dates (createTime:lt:now-1d), and value / attributes.<key> accept numeric comparisons on the number inside the text (value:gt:97) — see TQL search and filters.

Pagination

Parameter	Default	Description
`page`	`1`	Page number
`page-size`	Config default	Number of alerts per page

Example

List all critical production alerts, sorted by most recently received

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/alerts?environment=production&severity=critical&sort-by=-lastReceiveTime" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/alerts",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    params={
        "environment": "production",
        "severity": "critical",
        "sort-by": "-lastReceiveTime"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "page": 1,
  "pageSize": 50,
  "pages": 4,
  "more": true,
  "alerts": [ /* array of alert objects */ ],
  "total": {
    "severity": { "critical": 5, "warning": 12, "normal": 30 },
    "status": { "open": 17, "ack": 8, "closed": 22 },
    "environment": { "production": 25, "staging": 10, "dev": 12 },
    "source_id": { "nagios": 20, "cloudwatch": 17 },
    "trend_indication": { "moreSevere": 5, "lessSevere": 3, "noChange": 39 },
    "total": 47,
    "total_filtered": 47
  },
  "lastTime": "2025-04-15T10:30:00Z"
}

note

The total object contains global counts (unfiltered by your query) for all breakdown dimensions, plus total_filtered which reflects the current filter. This is useful for rendering sidebar badges without extra requests.

Errors

Code	Reason
`403`	User is not a member of the `all_events` group

List alerts by view

GET /api/alerts/by_view/<view_id>
Authorization: Key YOUR_API_KEY

Returns a paginated list of alerts belonging to a specific view (group). The user must be a member of the view or have admin scope.

Path parameters

Parameter	Description
`view_id`	The ID of the view (group) to query

Query parameters

Supports the same filtering, sorting, and pagination parameters as List All Alerts. Filters are combined with the view's own query using AND.

Example

List critical alerts for a specific view

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/alerts/by_view/VIEW_ID?severity=critical&sort-by=-lastReceiveTime&page-size=25" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/alerts/by_view/VIEW_ID",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    },
    params={
        "severity": "critical",
        "sort-by": "-lastReceiveTime",
        "page-size": "25"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

Same structure as List All Alerts. The total object reflects counts scoped to the view (before your additional filters), and total_filtered is the result after your filters are applied.

{
  "status": "ok",
  "page": 1,
  "pageSize": 50,
  "pages": 2,
  "more": false,
  "alerts": [ /* array of alert objects */ ],
  "total": {
    "severity": { "critical": 3, "warning": 5 },
    "status": { "open": 6, "ack": 2 },
    "environment": { "production": 8 },
    "source_id": { "nagios": 8 },
    "trend_indication": { "moreSevere": 1, "noChange": 7 },
    "total": 8,
    "total_filtered": 8
  },
  "lastTime": "2025-04-15T10:30:00Z"
}

Errors

Code	Reason
`403`	User does not have access to this view
`404`	View not found

List alerts by service

GET /api/alerts/by_service/<service_name>
Authorization: Key YOUR_API_KEY

Returns all alerts that include service_name in their service array. This is a simple, unfiltered endpoint with no pagination.

Path parameters

Parameter	Description
`service_name`	The service name to search for

Example

List all alerts for the payment-service service

Bash
Python

curl -X GET "http://your-tobealert.com:9000/api/alerts/by_service/payment-service" \
  -H "Content-Type: application/json" \
  -H "Authorization: Key YOUR_API_KEY"

import requests

response = requests.get(
    "http://your-tobealert.com:9000/api/alerts/by_service/payment-service",
    headers={
        "Content-Type": "application/json",
        "Authorization": "Key YOUR_API_KEY"
    }
)

if response.status_code in [200, 201]:
    print("Request successful")
    print(response.json())
else:
    print(f"Error: {response.status_code}")
    print(response.text)

Response

{
  "status": "ok",
  "total": 3,
  "alerts": [ /* array of alert objects */ ]
}

Advanced filtering examples

Filter by multiple severities

GET /api/alerts/by_view/prod-view?severity=critical&severity=major

Filter by date range

GET /api/alerts/by_view/prod-view?from-date=2025-04-01T00:00:00Z&to-date=2025-04-15T23:59:59Z

Filter by attribute value

GET /api/alerts/by_view/prod-view?attributes.region=us-west-2

Sort by most recent and paginate

GET /api/alerts/by_view/prod-view?sort-by=-lastReceiveTime&page=2&page-size=25

Filter by tag

GET /api/alerts/by_view/prod-view?tags=aws&tags=production

Filter by parent resource

GET /api/alerts/by_view/prod-view?resourceParent=vm-7

The same filter in TQL (dashboard search, views, filter builder) is resourceParent:eq:vm-7.

Overview​

Get a single alert​

Example​

Response​

Cause and effect fields​

Resource relation fields​

Errors​

List all alerts​

Query parameters​

Filtering​

Sorting​

Pagination​

Example​

Response​

Errors​

List alerts by view​

Path parameters​

Query parameters​

Example​

Response​

Errors​

List alerts by service​

Path parameters​

Example​

Response​

Advanced filtering examples​

Filter by multiple severities​

Filter by date range​

Filter by attribute value​

Sort by most recent and paginate​

Filter by tag​

Filter by parent resource​

Overview

Get a single alert

Example

Response

Cause and effect fields

Resource relation fields

Errors

List all alerts

Query parameters

Filtering

Sorting

Pagination

Example

Response

Errors

List alerts by view

Path parameters

Query parameters

Example

Response

Errors

List alerts by service

Path parameters

Example

Response

Advanced filtering examples

Filter by multiple severities

Filter by date range

Filter by attribute value

Sort by most recent and paginate

Filter by tag

Filter by parent resource