# Monitor REST API: Alarms ## Overview > \[!IMPORTANT] > > Alarms resources are currently available as a Private Beta product and the information contained in this document is subject to change. This means that some features aren't yet implemented and others may be changed before the product is declared as Generally Available. Private Beta products aren't covered by a SLA. 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. ## Key features * Create alarms to monitor metrics like error rates, usage thresholds, or latency. * Retrieve alarm configurations and statuses. * Update or delete existing alarms programmatically. ## Base URL ```bash https://monitor.twilio.com/v2/Alarms ``` ## Authentication To authenticate requests to the Twilio APIs, Twilio supports [HTTP Basic authentication](https://en.wikipedia.org/wiki/Basic_access_authentication). Use your *API key* as the username and your *API key secret* as the password. You can create an API key either [in the Twilio Console](/docs/iam/api-keys/keys-in-console) or [using the API](/docs/iam/api-keys/key-resource-v1). **Note**: Twilio recommends using API keys for authentication in production apps. For local testing, you can use your Account SID as the username and your Auth token as the password. You can find your Account SID and Auth Token in the [Twilio Console](https://www.twilio.com/console). Learn more about [Twilio API authentication](/docs/usage/requests-to-twilio). ## Example authorization header ```http Authorization: Basic {Base64Encoded(APIKey:APIKeySecret)} ``` ### Create an Alarm `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** | Header Name | Description | Required | | ----------------- | ----------------------------------------- | -------- | | Idempotency-Token | A unique key you provide for idempotency. | Yes | **Request Parameters** | Parameter | Description | Type | Required | | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------- | -------- | | `friendlyName` | A user-friendly name for your alarm. It must be between 1 and 64 characters long, containing only alphanumeric characters and spaces, and cannot be empty. | `string` | Yes | | `description` | A description of your alarm's purpose. This field is required and cannot be empty. | `string` | Yes | | `queryType` | The type of query to perform, such as `ERROR_CODE`, `LOG_LEVEL`, or `ALL`. Must be one of the supported query types. | `string` | Yes | | `query` | The specific query value. For `ERROR_CODE`, must be a numeric error code. For `LOG_LEVEL`, it must be either `WARNING`, `ERROR`, or `INFO`. For `ALL`, typically empty or not required. | `string` | Yes | | `triggerValue` | The value that triggers your alarm. Must be an integer of at least 1. If you provide a value below 1, the API will return a `400 Bad Request` error. | `integer` | Yes | | `timeWindow` | The time window to evaluate your alarm, such as `FIVE_MINS`, `FIFTEEN_MINS`, `ONE_HOUR`, `TWELVE_HOURS`, or `ONE_DAY`. Must be one of the supported time window values. | `string` | Yes | | `email` | A list of email addresses to notify. Can include up to 25 valid email addresses, each in proper email format (for example, `example@domain.com`). | `array` | No | | `webhook` | A URL for webhook notifications. Allows only one URL in a valid URL format, and must be less than 2000 characters. | `string` | No | | `consoleIndicator` | Whether to enable Console notifications for your alarm. At least one of `email`, `webhook`, or `console_indicator` must be enabled. | `boolean` | No | | `enabled` | Whether your alarm is enabled upon creation. | `boolean` | Yes | **Sample Request** ```bash curl -X POST https://monitor.twilio.com/v2/Alarms \ -u "AccountSID:AuthToken" \ -H "Idempotency-Token: 123e4567-e89b-12d3-a456-426614174000" \ -H "Content-Type: application/json" \ -d '{ "friendlyName": "High CPU Usage", "description": "An updated alarm for error code 404 occurrences exceeding the threshold.", "queryType": "ERROR_CODE", "query": "404", "triggerValue": 90, "timeWindow": "FIVE_MINS", "email": ["admin@example.com"], "webhook": "https://example.com/alerts", "consoleIndicator": true, "enabled": true }' ``` **Sample Response** ```json { "sid": "AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX" } ``` **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. ### Retrieve an Alarm `GET https://monitor.twilio.com/v2/Alarms/{AlarmSid}` Retrieve details of a specific alarm. **Sample Request** ```bash curl -X GET https://monitor.twilio.com/v2/Alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \ -u "AccountSID:AuthToken" ``` **Sample Response** ```json { "sid": "AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX", "friendlyName": "High CPU Usage", "description": "An updated alarm for error code 404 occurrences exceeding the threshold.", "queryType": "ERROR_CODE", "query": "404", "triggerValue": 90, "timeWindow": "FIFTEEN_MINS", "email": ["admin@example.com"], "webhook": "https://example.com/alerts", "consoleIndicator": true, "enabled": true, "product": "Multiple" } ``` ### Update an Alarm `PUT https://monitor.twilio.com/v2/Alarms/{AlarmSid}` Update an existing alarm configuration. **Request Parameters** | Parameter | Type | Description | Required | Validation | | ------------------ | --------- | ------------------------------------------------------------------------------------------------------------------- | -------- | ---------------------------------------------------------------------------------------- | | `friendlyName` | `string` | A user-friendly name for your alarm. | Yes | Must be between 1 and 64 characters, containing only alphanumeric characters and spaces. | | `description` | `string` | A description of your alarm's purpose. | Yes | Required. | | `queryType` | `string` | The type of query to perform, like `ERROR_CODE`, `LOG_LEVEL`, or `ALL`. | Yes | Must be a valid query type. | | `query` | `string` | The specific error code value or log level. | Yes | Must be a valid error code or log level. | | `triggerValue` | `integer` | The value that triggers your alarm. | Yes | Must be at least 1 (minimum value: 1). | | `timeWindow` | `string` | The time window to evaluate your alarm, like `FIVE_MINS`, `FIFTEEN_MINS`, `ONE_HOUR`, `TWELVE_HOURS`, or `ONE_DAY`. | Yes | Must be one of the supported time window values. | | `email` | `array` | A list of email addresses to notify. | No | Each email must be in valid email format. | | `webhook` | `string` | A URL for webhook notifications. | No | Only one URL is allowed. Must be a valid URL format. | | `consoleIndicator` | `boolean` | Whether to enable console notifications for your alarm. | No | At least one of `email`, `webhook`, or `console_indicator` must be enabled. | | `enabled` | `boolean` | Whether your alarm is enabled. | Yes | Required. | **Sample Request** ```bash curl -X PUT https://monitor.twilio.com/v2/Alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \ -u "AccountSID:AuthToken" \ -H "Content-Type: application/json" \ -d '{ "friendlyName": "High CPU Usage", "description": "An alarm for CPU usage exceeding 90%.", "queryType": "ERROR_CODE", "query": "404", "triggerValue": 90, "timeWindow": "FIFTEEN_MINS", "email": ["admin@example.com"], "webhook": "https://example.com/alerts", "consoleIndicator": true, "enabled": true }' ``` **Sample Response** ```json { "sid": "AKv2xxxxxxxxxxxxxxxxxxxxxxx" } ``` ### Delete an Alarm `DELETE https://monitor.twilio.com/v2/Alarms/{AlarmSid}` Delete an existing alarm. **Sample Request** ```bash curl -X DELETE https://monitor.twilio.com/v2/Alarms/AKXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX \ -u "AccountSID:AuthToken" ``` **Sample Response** ```bash HTTP Status Code: 204 No Content ``` ## Response codes The API returns standard HTTP response codes to indicate success or failure. | Code | Meaning | Description | | ---- | --------------------- | ------------------------------------------------ | | 200 | OK | Request succeeded. | | 201 | Created | Alarm was successfully created. | | 204 | No Content | Alarm was successfully deleted. | | 400 | Bad Request | Invalid input or missing required fields. | | 401 | Unauthorized | Invalid credentials. | | 404 | Not Found | Alarm or resource doesn't exist. | | 409 | Conflict | Account exhausted the limit of number of alarms. | | 500 | Internal Server Error | An error occurred on the server. | ## Best practices * 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**.