Monitor REST API: Alarms

The Alarms API enables you to monitor and manage Twilio resources by setting up, retrieving, updating, and deleting alarms for specific metrics. With this API, you can stay informed about critical issues and automate responses to ensure your applications run smoothly.

After reading this document, you will be able to use the Alarms API to create, retrieve, update, and delete alarms for monitoring your Twilio resources.

• Create alarms to monitor metrics like error rates, usage thresholds, or latency.
• Retrieve alarm configurations and statuses.
• Update or delete existing alarms programmatically.

The Alarms API uses the same HTTP Basic Authentication as other Twilio APIs. Use your Twilio Account SID as your username and your Auth Token as your password.

POST https://monitor.twilio.com/v2/alarms

Create a new alarm configuration with specified parameters. This operation is idempotent, ensuring that repeated requests with the same Idempotency-Token will not create duplicate alarms.

Headers

Request Parameters

Sample Request

1
curl -X POST https://monitor.twilio.com/v2/alarms \
2
-u "AccountSID:AuthToken" \
3
-H "Idempotency-Token: 123e4567-e89b-12d3-a456-426614174000" \
4
-H "Content-Type: application/json" \
5
-d '{
6
  "friendlyName": "High CPU Usage",
7
  "description": "An alarm for CPU usage exceeding 90%.",
8
  "queryType": "ERROR_CODE",
9
  "query": "404",
10
  "triggerValue": 90,
11
  "timeWindow": "FIVE_MINS",
12
  "email": ["admin@example.com"],
13
  "webhook": "https://example.com/alerts",
14
  "consoleIndicator": true,
15
  "enabled": true
16
}'

Sample Response

1
{
2
  "sid": "AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX"
3
}

Maximum Alarms limit

• You can create up to 100 alarms per account.
• If you attempt to create more than 100 alarms, the API will return a 409 Conflict error with a message indicating the limit has been reached.

GET https://monitor.twilio.com/v2/alarms/{AlarmSid}

Retrieve details of a specific alarm.

Sample Request

1
curl -X GET https://monitor.twilio.com/v2/alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2
-u "AccountSID:AuthToken"

Sample Response

1
{
2
  "sid": "AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX",
3
  "friendlyName": "High CPU Usage",
4
  "description": "An alarm for CPU usage exceeding 90%.",
5
  "queryType": "ERROR_CODE",
6
  "query": "404",
7
  "triggerValue": 90,
8
  "timeWindow": "FIFTEEN_MINS",
9
  "email": ["admin@example.com"],
10
  "webhook": "https://example.com/alerts",
11
  "consoleIndicator": true,
12
  "enabled": true,
13
  "product": "Multiple"
14
}

PUT https://monitor.twilio.com/v2/alarms/{AlarmSid}

Update an existing alarm configuration.

Request Parameters

Sample Request

1
curl -X PUT https://monitor.twilio.com/v2/alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2
-u "AccountSID:AuthToken" \
3
-H "Content-Type: application/json" \
4
-d '{
5
  "friendlyName": "High CPU Usage",
6
  "description": "An alarm for CPU usage exceeding 90%.",
7
  "queryType": "ERROR_CODE",
8
  "query": "404",
9
  "triggerValue": 90,
10
  "timeWindow": "FIFTEEN_MINS",
11
  "email": ["admin@example.com"],
12
  "webhook": "https://example.com/alerts",
13
  "consoleIndicator": true,
14
  "enabled": true
15
}'

Sample Response

1
{
2
  "sid": "AKv2xxxxxxxxxxxxxxxxxxxxxxx"
3
}

DELETE https://monitor.twilio.com/v2/alarms/{AlarmSid}

Delete an existing alarm.

Sample Request

1
curl -X DELETE https://monitor.twilio.com/v2/alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \
2
-u "AccountSID:AuthToken"

Sample Response

HTTP Status Code: 204 No Content

The API returns standard HTTP response codes to indicate success or failure.

• Use descriptive names for your alarms to quickly identify them.
• Test your webhook endpoint to ensure it handles alerts reliably.
• Regularly review and update your alarm configurations to match your system's needs.
• Keep track of the number of alarms you create to ensure you don't exceed the limit of 100 alarms.