Skip to main content
Alerts API

This tutorial will help you use our alerts API to define, query, and manage your alerts. 

Zvika Kozniak avatar
Written by Zvika Kozniak
Updated over 3 years ago

API URL:

Authentication 

API Access

In Settings --> Account, Choose 'Alerts API Access' option and generate new API key:

** Note that only admin users have access to the API, So the option above will be visible only to admin users.

The generated API key must be added to the header of each HTTP request to the API, you’ll need to configure it as a 'Bearer Token':

  1. Authorization: bearer YOUR_API_KEY

  2. Content-Type: application/json

"POST" Create New Alert

Body parameters

Parameter

Description

Type

Note

name

Alert name

string

severity

Alert severity

string

must be one of the following options: [“info”, “warning”, “critical”]

is_active

A boolean that determines whether the alert is active or not

boolean

log_filter

An object that represents the filter definition of the alert

object

Each property of that object is described below

log_filter.text

The query_string query that we wanted to be notified on. can be in an “advanced” format for more accurate results.

string(case sensitive)

log_filter.category

An array that contains log’s categories that we want to be notified on

array

log_filter.filter_type

Type of the log filter

string

must be one of the following options: [“text”, “ratio”, “unique_count”, “relative_time”]

For 'new_value' alerts the value should be "text"

log_filter.severity

An array of log severities that we interested in

array

Must be chosen from the following options: [“debug”, “verbose”, “info“, “warning”, “error“, critical”]

log_filter.application_name

An array that contains log’s application names that we want to be alerted on

array

log_filter.subsystem_name

An array that contains log’s subsystem names that we want to be notified on

array

log_filter.computer_name

An array that contains log’s computer names that we want to be notified on

array

log_filter.class_name

An array that contains log’s class names that we want to be notified on

array

log_filter.ip_address

An array that contains log’s IP addresses that we want to be notified on

array

log_filter.method_name

An array that contains log’s method names that we want to be notified on

array

condition

An object that specifies a condition for triggering the alert

object or string with null value that represents 'immediate' alert

Each property of that object is described below

condition.condition_type

Type of the condition

string

must be one of the following options: [‘less_than’, ‘more_than’, ‘more_than_usual’, ‘new_value’]

For 'unique_count' alerts the value should be "more_than"

condition.threshold

The number of log occurrences that is needed to trigger the alert

number

condition.timeframe

The bounded time frame for the threshold to be occurred within, to trigger the alert

string

must be one of the following options: [‘5Min‘, 10Min’, ‘20Min’, ‘30Min’, ‘1H’, ‘2H’, ‘3H’, ‘4H’, ‘6H’, ‘12H’, ‘24H’]

For 'new_value' alerts you should send one of the following options:
[‘12H’, ‘24H’, ‘48H’, ‘72H’, ‘1W’, ‘1M’, ‘2M’, ‘3M’]

condition.group_by

The field to 'group by' on

string

The name of the key, if nested than specify full path.

For 'new_value' alerts it must contain a value

notifications

An object that specifies which notifications channels to use when an alert was triggered

object

Each property of that object is described below

notifications.emails

An array of email address to notify when the alert was triggered

array

notifications.integrations

An array of integration channels to notify when the alert was triggered

array

Each item in the array is the alias name of the integration

notify_every

the supress time for the Alert

number (in seconds)

By default, when creating an Alert through the UI or with the API, notify_every will be populated with 60(sec) for immediate, more and more than alerts. For less than alert it will be populated with the chosen time frame for the less condition (in seconds).
You may choose to change the suppress window so the alert will be suppressed for a longer period.

description

alert description

string

notif_payload_filter

An array that contains log fields out of the log example that we want to be included with the alert notification

array

Showing 1 to 25 of 25 entries

Example

This is an example payload for alert creation via the API. The response of that request returns an alert_id. You can save this id in case you want to update the alert later on.

{ "name": "Security Alert", "severity": "info", "is_active": true, "log_filter": { "text": "authentication failed", "category": null, "filter_type": "text", "severity": ["error", "critical"], "application_name": ["production"], "subsystem_name": ["my-app", "my-service"], "computer_name": null, "class_name": null, "ip_address": null, "method_name": null }, "condition": { "condition_type": "more_than", "threshold": 100, "timeframe": "10MIN", "group_by": "host" }, "notifications": { "emails": ["[email protected]", "[email protected]"], "integrations": ["security-slack", "security-pagerduty"] }, "notify_every": 60, "description": "", "active_when": { "timeframes": [{ "days_of_week": [ 1, 3, 4, 5, 2 ], "activity_ends": "10:00:59", "activity_starts": "05:00:00" }] }, "notif_payload_filter": [ "message" ] }Copy

Result Format

201 Created { "status": "success", "message": "Alert created successfully", "alert_id": "uuid" }Copy
400 Bad Request { "status": "invalid alert", "message": "Non valid value was received for field", "errors": [ "err_reason1", "err_reason2" ] }Copy
403 Forbidden201 Created { "status": "alerts limit exceeded", "message": "Company was reached the maximum alerts it can produce", "limit": "company’s alerts limit" //Usually it's 500 }Copy

“PUT”, Update Alert

Body parameters

Parameter

Description

Type

Note

id

The UUID that identifies the alert on the system

string

Mandatory

Alerts fields

You can add to the request every field that you want to update.
See the body params of the POST request above. Note, if you are updating an alert and you set 'condition.group_by' to be empty string or null, it will update the alert and remove the 'group by' field if exists.

Showing 1 to 2 of 2 entries

Note

If you are updating one of the following fields, a new Alert is created behind the scene and the id of the alert thus changes. You should consider that when performing updates for your alerts via the API as the id is mandatory in PUT requests.

log_filter.severity log_filter.text log_filter.computer_name log_filter.application_name log_filter.subsystem_name log_filter.category log_filter.class_name log_filter.method_name log_filter.ip_address log_filter.process condition.group_by condition.threshold condition.timeframe condition.condition_type notify_everyCopy

Example:

This is an example payload for updating an alert via the API. In the case below, we just want to update the name of the alert.

{ "id": "bbe51650-e080-11ea-bd23-cd528faf6870", "name": "New Name!" }Copy

Result Format

201 Ok { "id": "bbe51650-e080-11ea-bd23-cd528faf6870", "status": "success", "message": "Alert updated successfully" }Copy
400 Bad Request { "status": "invalid alert", "message": "Non valid value was received for field", "errors": [ "err_reason1", "err_reason2" ] }Copy
404 Not Found { "status": "alert not found", "message": "Failed to update alert" }Copy

Example 2:

This is an example payload for updating an alert via the API. In the case below, we want to update the condition timeframe for our more than Alert. We updated from 5MIN to half an hour. As described in the prior note, this will generate a new alert and the response will reveal to us the new alert id for future use.

{ "id": "bbe51650-e080-11ea-bd23-cd528faf6870", "condition": { "timeframe": "30MIN" } }Copy

Result Format

201 Ok { "id": "3c719e80-087f-11eb-bcc2-d587e83de7b5", "status": "success", "message": "Alert updated successfully" }Copy
400 Bad Request { "status": "invalid alert", "message": "Non valid value was received for field", "errors": [ "err_reason1", "err_reason2" ] }Copy
404 Not Found { "status": "alert not found", "message": "Failed to update alert" }Copy

“Delete”, Delete Alerts

Body parameters

Parameter

Description

Type

Note

id

The UUID that identifies the alert on the system

string

Showing 1 to 1 of 1 entries

Result Format

200 Ok { "status": "success", "message": "Alert deleted successfully" }Copy
400 Bad Request { "status": "invalid id", "message": "Non valid value was received for field", "errors": [ "invalid_id_err_msg" ] }Copy
404 Not Found { "status": "alert not found", "message": "Failed to delete alert" }Copy

“GET”, Query your Alerts

Query parameters

Parameter

Description

Type

Note

applicationName

Will check if it contained in the alert’s log_filter.application_name array

string(case sensitive)

subsystemName

Will check if it contained in the alert’s log_filter.subsystem_name array

string(case sensitive)

severity

Query by alert’s severity

string

Must be one of the following options: [“info”, “warning”, “critical”]

fromTimestamp

Query all alerts that have been created from a specific timestamp until now

string - ISO format

"2020-06-07T17:30:00.000Z"

Showing 1 to 4 of 4 entries

** Note – You should pass the query parameters for ‘GET’ request through its URL in the following manner:

https://api.coralogix.com/api/v1/external/alerts?severity=warning&applicationName=metro-prod&subsystemName=metro-web&fromTimestamp=2020-06-07T17:30:00.000ZCopy

This URL will get in response all the alerts with ‘warning’ severity (alert level not log level), application metro-prod, subsystem metro-web, and were created after 17:30 on June 7th. The fromTimestamp should be a string in ISO format, you don’t have to specify the hour, date like &fromTimestamp=2020-06-07 will suffice to get all alerts that were created since June 7th 2020.

If you use none you will get in response all of your alerts.

Result Format:

200 Ok { "total": results_count, //number "message": [alerts..] //array }Copy
400 Bad Request { "status": "invalid query param", "message": "Non valid value was received for field", "errors": [ "err_reason1", "err_reason2" ] }Copy

Export all alerts to a new Coralogix team

In case you opened a new Coralogix team and you want to import all of your alerts from another team, first GET all the alerts from the first Coralogix team. In response, you will receive a JSON that includes all of your alerts. Copy it. Second, you will need to create a POST request (don’t forget to also change the API key to a key you generated from the new Coralogix team you opened) and paste the response from the former action as your POST request body. You will also need to change the URL for the request and add /bulk, e.g. https://api.coralogix.com/api/v1/external/alerts/bulk.

Appendix


How to run a complex query inside the log_filter.text field


Run a complex query, use / before and after your text.

  • To perform a free text search, simply enter a text string. For example, if you are searching your web server logs, enter safari to define an alert on all fields for the term safari (without/around the alert text).

  • To define an alert on a value in a specific field, prefix the value with the name of the field. For example, enter /environment:production/ to define an alert on all the entries that contain the value production in the environment field.

  • To define an alert on a range of numeric values, use the bracketed range syntax [START_VALUE TO END_VALUE]. For example, to define an alert on entries that have 4xx status codes, enter /status.numeric:[400 TO 499]/.

  • To specify more complex alert criteria, use the Boolean operators AND, OR, and NOT. For example, to define an alert on entries that have 4xx status codes and have an extension of PHP, enter /status.numeric:[400 TO 499] AND extension:php/.

  • To define an alert when a regular expression matches a value, wrap your regex with ‘/’ and use it as the expression for the field. For example, to define an alert the regions west-europe-1, west-europe-2, west-us-1, west-us-2, west-us-3 etc., enter /region:/west-(europe|us)-[0-9]+//.

Example: define an alert on logs from your production with status codes 5xx not originating from west-europe or west-us, use this expression:

/environment:production AND status.numeric:[500 TO 599] NOT region:/west-(europe|us)-[0-9]+//


Did this answer your question?