Alerts

• List Alerts
• Get Alert
• Update Alert
• Close Alerts
• Get Alert Logs

List Alerts

This will get the list of alerts.

GET /api/v0/alerts

Required permissions for the API key

• Read

Input (Query parameters)

You can filter alerts with the following parameters. If withClosed is not specified, only open alerts are returned. If nextId is not specified, alerts will be returned in order of latest occurrence time.

PARAM	TYPE	DESCRIPTION
withClosed	boolean	[optional] Whether or not to get resolved alerts. If true, resolved alerts as well as open alerts are retrieved.
nextId	string	[optional] If nextId is specified, alerts older than the alert with the specified id are retrieved.
limit	number	[optional] The maximum number of alerts to retrieve. When omitted, up to 100 cases are retrieved. The most that can be specified is 100.

Response

{
  "alerts": [<alert>, <alert>, ...],
  "nextId": xxx
}

Alerts will be returned in chronological order of when they were generated from newest to oldest. The nextId field is returned only when there are more alerts existing.

<alert>: an object that holds the following keys.

KEY	TYPE	DESCRIPTION
id	string	the alert's ID
status	string	the alert's current status: "OK", "CRITICAL", "WARNING", or "UNKNOWN"
monitorId	string	the ID of the monitor that generated the alert
type	string	the type of the monitor: connectivity ("connectivity"), host metric ("host"), service metric ("service"), external monitor ("external"), check monitor ("check"), expression monitor ("expression"), anomaly detection for roles ("anomalyDetection"), or query monitor ("query")
hostId	string	[optional] the associated host ID. only exists when the type of the monitor is either "connectivity", "host", "check", or "anomalyDetection"
series	object	[optional] the monitoring series. only exists when the type of the monitor is "query" *1
value	number	[optional] the value of the monitoring target. only exists when the type of the monitor is "host", "service" or "query", or when there is a response time configuration in "external"
message	string	[optional] the monitoring target's message. only exists when the type of the monitor is either "check" or "external"
reason	string	[optional] the reason the alert closed. does not exist if the alert is unresolved.
openedAt	number	the timestamp of when the alert was generated (Unix time)
closedAt	number	[optional] the timestamp of when the alert was resolved (Unix time). only exists if the alert is already resolved

*1 series

series is an object that holds the following keys.

KEY	TYPE	DESCRIPTION
name	string	the name of the monitoring series, e.g. "container.cpu.utilization"
labels	object	the labels of the monitoring series. an object consisting of keys and a values, where the keys and values of each label are stored, e.g. {"ip":"127.0.0.1"}

Error

STATUS CODE	DESCRIPTION
400	when `limit` value is larger than the maximum allowed value (100)

---

Get Alert

GET /api/v0/alerts/<alertId>

Required permissions for the API key

• Read

Response

Success

The alert is returned. The response format is the same as that which can be obtained with List Alerts.

Error

STATUS CODE	DESCRIPTION
404	when the specified alert does not exist

---

Update Alert

PUT /api/v0/alerts/<alertId>

Required permissions for the API key

• Read
• Write

Input

{
  "memo": "<text>"
}

Any text can be appended in the memo field. This field is a required item.

Response

Success

alert's ID and memo are returned.

  "id": "<alertId>",
  "memo": "<text>"

Error

STATUS CODE	DESCRIPTION
403	when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range
404	when the specified alert does not exist
413	when the memo exceeds 80KB

---

Close Alerts

The designated alert will be closed.

POST /api/v0/alerts/<alertId>/close

Required permissions for the API key

• Read
• Write

Input

{
  "reason": "<text>"
}

Any text can be appended in the reason field. This field is a required item.

Response

Success

A post-update alert will be returned.

{
  "id": "<alertId>",
  "status": "OK",
  ...
  "reason": "<reason>",
  "openedAt": <openedAt>,
  "closedAt": <closedAt>
}

The response object includes the same keys as the <alert> object in Getting Alerts. Here, the reason and closedAt fields are not optional, they will always exist.

Error

STATUS CODE	DESCRIPTION
404	when the alert with the corresponding <alertId> can't be found
403	when the API key doesn't have the required permissions / when accessing from outside the permitted IP address range

---

Get Alert Logs

This will get the list of alert logs.

GET /api/v0/alerts/<alertId>/logs

Required permissions for the API key

• Read

Input (Query parameters)

If nextId is not specified, alert logs will be returned in order of latest occurrence time.

PARAM	TYPE	DESCRIPTION
nextId	string	[optional] If nextId is specified, alert logs older than the specified are retrieved.
limit	number	[optional] The maximum number of alert logs to retrieve. When omitted, up to 100 logs are retrieved. The most that can be specified is 100.

Response

Success

{
  "logs": [<log>, <log>, ...],
  "nextId": xxx
}

The logs will be returned in order of occurrence time. nextId is returned when there are more than limit alerts.

<log>: an object that holds the following keys.

KEY	TYPE	DESCRIPTION
id	string	the alert log's ID
status	string	the status of the alert at the time the log was generated: "OK", "CRITICAL", "WARNING", or "UNKNOWN".
trigger	string	the type of reason why the log was created: monitoring rule ("monitoring"), manual ("manual"), monitoring rule deletion ("monitorDelete"), host retirement ("hostRetire"), service deletion ("serviceDelete"), manual retraining of anomaly detection for roles ("anomalyDetectionManuallyRetraining"), or change of service linked to external monitoring ("externalMonitoringServiceChange").
monitorId	string / null	the ID of the monitoring rule that created the log. it will be null if the monitoring rule has been changed or deleted at the time of the request.
targetValue	number / null	the observed value. if the alert is not from metric monitoring, it will be null.
statusDetail	object / null	detailed state of the monitored target. it only exists for check monitoring. *1
createdAt	number	the creation date of the log (Unix time).

*1 statusDetail

statusDetail: an object that holds the following keys.

KEY	TYPE	DESCRIPTION
type	string	The type of monitoring rule. It will always be check.
detail	object	Detailed information about the state. *2

*2 detail

detail: an object that holds the following keys.

KEY	TYPE	DESCRIPTION
message	string	The result of the check monitoring posted to Mackerel.
memo	string	The memo of the monitoring rule.

Error

STATUS CODE	DESCRIPTION
400	when limit value is larger than the maximum allowed value (100)
404	when the specified alert does not exist