Version: 1.2

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"
  }
}

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	`?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	`?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

Supported sort fields: id, resource, event, environment, severity, status, group, origin, createTime, lastReceiveTime, updateTime, duplicateCount, trendIndication, value, tags.

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

Overview​

Get a single alert​

Example​

Response​

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​

Overview

Get a single alert

Example

Response

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