Our next-gen architecture is built to help you make sense of your ever-growing data. Watch a 4-min demo video!

Back to All Docs

Alerts API Alerts API

Last Updated: Jan. 08, 2024

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

New! Alerts API now supports our expanded Notification Group By alert settings:

  • Notification Group By alerts by one or more keys. An alert is triggered whenever the condition threshold is met for a specific aggregated value within the specified timeframe. If using 2 keys for Group By, an alert will fire when the threshold meets the unique combination of both keys.
  • An individual notification for each of the values of the Group By keys will be sent when query conditions are met. For example, if the conditions set are met in 3 different regions, three separate notifications will be sent – one for region X, one for region Y, and one for region Z.

API URL

Select the External Alerts endpoint associated with your Coralogix domain.

Notes:

  • v1 base API endpoint has been changed to v2, given deprecated fields in v1.
  • Customers using v1 will lose certain functionalities and cannot enjoy individual notifications for each of the values of the Group By field.

API Access

API Access generation

STEP 1. In your navigation pane, click Data Flow > API Keys.

STEP 2. Click GENERATE NEW API KEY in the section entitled Alerts, Rules and Tags API Key. Copy the new key.

Note: Only admins are authorized to view this API Key.

STEP 3. The generated Alerts, Rules and Tags API Key must be added to the header of each HTTP request to the API. Configure it as a ‘Bearer Token’.

Authorization: bearer YOUR_API_KEY.

STEP 4. Define the header Content-Type as application/json.

Content-Type: application/json

“POST” Create New Alert

Body Parameters

ParameterDescriptionTypeNotes
nameAlert Typestring
severityAlert Severitystringmust be one of the following options: [“info”, “warning”, “critical”]
is_activeA boolean that determines whether the alert is active or notboolean
log_filterAn object that represents the filter definition of the alertobjectEach property of that object is described below
log_filter.textThe 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.categoryAn array that contains log’s categories that we want to be notified onarray
log_filter.filter_typeType of the log filterstringmust be one of the following options: [“text”, “ratio”, “unique_count”, “relative_time”, “metric”]

For ‘new_value’ alerts the value should be “text”
log_filter.severityAn array of log severities that we interested inarrayMust be chosen from the following options: [“debug”, “verbose”, “info“, “warning”, “error“, critical”]
log_filter.application_nameAn array of strings that includes the different matches for application names filtersarrayThere are 4 types of matching criteria: ‘Is’, ‘Start With’, ‘Includes’, ‘Ends With’

E.g.
log_filter.application_name: [“production”, “filter:startsWith:prod”, “filter:contains:duct”, “filter:endsWith:ion”]
log_filter.subsystem_nameAn array of strings that includes the different matches for subsystem names filtersarrayThere are 4 types of matching criteria: ‘Is’, ‘Start With’, ‘Includes’, ‘Ends With’

E.g.
log_filter.subsystem_name: [“my-nice-app”, “filter:startsWith:my”, “filter:contains:nice”, “filter:endsWith:app”]
log_filter.computer_nameAn array that contains log’s computer names that we want to be notified onarray
log_filter.class_nameAn array that contains log’s class names that we want to be notified onarray
log_filter.ip_addressAn array that contains log’s IP addresses that we want to be notified onarray
log_filter.method_nameAn array that contains log’s method names that we want to be notified onarray
log_filter.aliasA string of text for Query 1 alias. Relevant to ratio alerts onlystring
log_filter.ratioAlertsAn array containing an object representing Query 2 for ratio alertsarrayKeys supported in Query2 object are:
application_name
subsystem_name
severity
text
alias
group_by – array of strings with group by fields. If the root alert has defined group_by it has to be the same or empty. If root alert doesn’t have group_by you can choose specific group_by for Query 2.
The description of the keys is same as above
conditionAn object that specifies a condition for triggering the alertobject or string with null value that represents ‘immediate’ alertEach property of that object is described below
condition.condition_typeType of the conditionstringmust 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”
For ‘metric’ alerts, the value can be one of [‘less_than’, ‘more_than’]
condition.unique_count_keyUnique count key namestringSelect from list of keys.
condition.thresholdThe number of log occurrences that is needed to trigger the alertnumber
condition.timeframeThe bounded time frame for the threshold to be occurred within, to trigger the alertstringmust 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’]
For ‘relative_time’ alerts you should send one of the following options:
[‘HOUR’, ‘DAY’]
condition.relative_timeframetimeframe to compare with (relevant on with ‘Time Relative Alers’stringstring must be one of the following options: [‘HOUR’, ‘DAY’, ‘WEEK’, ‘MONTH’]
condition.group_byThe field to ‘group by’ onstring or arrayThe name of the key, if nested then specify the full path.

Relevant only for: ‘more than’, ‘more than usual’, ‘new value’, ‘unique count’, and ‘metric’ alerts.

Using an array for the group_by property will aggregate by multiple labels.

For ‘new_value’ alerts it must contain a value
condition.group_by_lvl2The subsequent field to ‘group by’ onstringThe name of the key, if nested then specify the full path.

Relevant only for: ‘more than’ alert.
condition.metric_fieldThe name of the metric field to alert onstringRequired for Metric alert type only
condition.metric_sourceThe source of the metric. Either ‘logs2metrics’ or ‘prometheus’stringRequired for Metric alert type only
condition.arithmetic_operator0 – avg, 1 – min, 2 – max, 3 – sum, 4 – count, 5 – percentile (for percentile you need to supply the requested percentile in arithmetic_operator_modifier)numberRequired for Metric alert type only
condition.arithmetic_operator_modifierfor percentile(5) arithmetic_operator you need to supply the value in this propertynumberRequired for Metric alert type only
condition.sample_threshold_percentageThe metric value must cross the threshold within this percentage of the timeframe (sum and count arithmetic operators do not use this parameter since they aggregate over the entire requested timeframe), increments of 10, 0<=value<=90numberRequired for Metric alert type only
condition.non_null_percentagethe minimum percentage of the timeframe that should have values for this alert to trigger. increments of 10, 0<=value<=100numberRequired for Metric alert type only
condition.swap_null_valuesIf set to true, missing data will be considered as 0, otherwise, it will not be considered at allbooleanRequired for Metric alert type only
notificationsAn object that specifies which notifications channels to use when an alert was triggeredobjectEach property of that object is described below
notifications.emailsAn array of email address to notify when the alert was triggeredarray
notifications.integrationsAn array of integration channels to notify when the alert was triggeredarrayEach item in the array is the alias name of the integration
notify_everythe supress time for the Alertnumber (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.
descriptionalert descriptionstring
notif_payload_filterAn array that contains log fields out of the log example that we want to be included with the alert notificationarray
meta_labelsAn array can contain objects with structure {“key”: “MY_KEY”, “value”: “MY_VALUE”}, or ‘:’ delimited strings with pattern “MY_KEY:MY_VALUE”.array‘key’ must be only letters or digits, but can include ‘_’, or ‘-’. both ‘key’ and ’value must be no longer than 255
log_filter.tracing.fieldFiltersAn array that contain filter for Application, Subsystem, serviceNamelog_filter.tracing.fieldFilters:[{“field”:”field“},”filters”:[“fields”:[“value1″,”value2″,…],”operator”:”operator“]]
options for “field” (meta fields):
“field”:applicationName”, “subsystemName”,”serviceName”

Options for “Operator” field: “operator”:”equal”,”startsWith”,”contain”,”endsWith”
log_filter.tracing.tagFiltersAn array that contains filters for tagsarraylog_filter.tracing.tagFilters:[{“field”:”tag to monitor”},”filters”:[“fields”:[“value1″,”value2″,…],”operator”:”operator*”]]

Options for “Operator” field: “operator”:”equal”,”startsWith”,”contain”,”endsWith”
log_filter.tracing.conditionLatencyNumeric value for latency (will monitor value above the parameter set)number
cleanup_deadman_durationThis parameter sets a value for Advanced “Auto retire values” parameterstring or nullThis is an optional parameter only relevant for Standard Alerts with the condition Less-than with GroupBy

The value should be one of the following:
[null, ‘5min’, ’10min’, ‘1h’, ‘2h’, ‘6h’, ’12h’, ’24h’]

Create alert scenario:
When omitted from the alert payload, the value defaults to null (Auto retire is disabled)

Update alert scenario:
When omitted from the alert payload, the previous value of this parameter will be retained

Note:

  • The following parameters are deprecated in v2: notify_every, notifications, notifications.emails, and notifications.integrations.

v2 Fields

ParameterDescriptionTypeNotes
show_in_insight.retriggeringPeriodSeconds
*deprecated*
the “Retriggering” period for the alert to be shown in the coralogix insights screennumber [Optional]
show_in_insight.notifyOn
*deprecated*
The “Notify on” parameter is used to define if we want to show the “resolve” event in the insight screenenum[Optional]“triggered_only” / “triggered_and_resolved”
notification_groups[].groupByFieldsA separate notification will be sent based on the “GroupByFields” labels(must be a sub-group of the alert group by labels)array[Optional]
notification_groups[].notifications[].retriggeringPeriodSecondsthe “Retriggering” period for the specific notification target setting in this notification groupnumber[Optional]
notification_groups[].notifications[].notifyOnThe “Notify on” for the specific notification target setting in this notification groupenum[Optional]“triggered_only” / “triggered_and_resolved”
notification_groups[].notifications[].integrationIdThe IntegrationId ( target)for the specific notification target setting in this notification group ( the same notification target settings cannot have emailRecipients and IntegrationId ( only oneOf ) )number
notification_groups[].notifications[].emailRecipientsThe email recipients ( target)for the specific notification target setting in this notification group( the same notification target settings cannot have emailRecipients and IntegrationId ( only oneOf ) )array
incident_settings.retriggeringPeriodSecondsThe “Retriggering” period for the alert to be shown in the coralogix incident screennumber [Optional]defaults : 10 minutes
incident_settings.notifyOnThe “Notify on” parameter is used to define if we want to show the “resolve” event in the incident screenenum[Optional]“triggered_only” / “triggered_and_resolved”
defaults: “triggered_only”
incident_settings.useAsNotificationSettingsShould be used as the settings for each outgoing webhookboolean[Optional]defaults: true

Example

This is an example payload for alert creation via the API. The response to that request returns an alert_id. Save this ID to update it at a later stage.

{

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

},

"show_in_insight": {

					"retriggeringPeriodSeconds": 120,
          "notifyOn":"triggered_and_resolved",
},

"notification_groups": [{
				"groupByFields": ["host"],
                          "notifications":[
                            {
                              "retriggeringPeriodSeconds": 120,
                              "notifyOn":"triggered_and_resolved",
                              "emailRecipients": ["[email protected]"]
                            },
                           {
                          "retriggeringPeriodSeconds": 240,
                          "notifyOn":"triggered_only",
                          "intergrationId": 1234512
                      }]
		},{
				"groupByFields": [],
                          "notifications":[
                            {
                              "retriggeringPeriodSeconds": 240,
                              "notifyOn":"triggered_and_resolved",
                              "emailRecipients":["[email protected]"]
                 
		}]
}],

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

]

}

Result Format

201 Created
{
  "status": "success",
  "message": "Alert created successfully",
  "alert_id": [
      "261e2741-8437-4397-926f-02d7390622a7"
  ],
  "unique_identifier": [
      "ba4c6eae-c3d9-4bb3-a670-faf35a488413"
  ]
}
400 Bad Request
{
  "status": "invalid alert",
  "message": "Non valid value was received for field",
  "errors": [
    "err_reason1",
    "err_reason2"
  ]
  "warnings": []
}
403 Forbidden
{
  "status": "alerts limit exceeded",
  "message": "Company was reached the maximum alerts it can produce",
  "limit": "company’s alerts limit" //Usually it's 500
}

Notes:

  • Two IDs are created in the example:
    • alert_id is the ID for tracking exactly that alert with all those parameters
    • unique_identifier is the ID for tracking that alert even if later any parameters will be changed
  • The difference will be explained with the example in the PUT part. Both can be used with PUT and DELETE requests.
  • The notificationGroup and showInInsight parameters in the example above reflects the following Notification Group settings and Coralogix Insights page settings :

“PUT”, Update Alert

Body Parameters

ParameterDescriptionTypeNote
idThe UUID that identifies the alert on the systemstringMandatory if there is not the “unique_identifier” field
unique_identifierAn alert unique identifierstringMandatory if there is not the “id” field
Alert fieldsYou 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.

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. You can also use unique_identifier instead which is not changed during any operation.

    log_filter.severity
    log_filter.text
    log_filter.application_name
    log_filter.subsystem_name
    condition.group_by
    condition.threshold
    condition.timeframe
    condition.condition_type
    notify_every

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": "c892ecf7-ee83-4484-9682-266d351be918",
  "name": "New Name!"
}

Result Format

201 Ok
{
  "status": "success",
  "message": "Alert updated successfully",
  "alert_id": "c892ecf7-ee83-4484-9682-266d351be918",
  "unique_identifier": "ba4c6eae-c3d9-4bb3-a670-faf35a488413"
}
400 Bad Request
{
  "status": "invalid alert",
  "message": "Non valid value was received for field",
  "errors": [
    "err_reason1",
    "err_reason2"
  ],
  "warnings": []
}
404 Not Found
{
  "status": "alert not found",
  "message": "Failed to update alert"
}

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 but the unique_identifier is still the same.

{
    "id": "c892ecf7-ee83-4484-9682-266d351be918",
    "condition": {
        "timeframe": "30MIN"
    }
}

Result Format

201 Ok
{
  "status": "success",
  "message": "Alert updated successfully",
  "alert_id": "bb56345b-22be-4570-ba08-3320a8821a69",
  "unique_identifier": "ba4c6eae-c3d9-4bb3-a670-faf35a488413"
}
400 Bad Request
{
  "status": "invalid alert",
  "message": "Non valid value was received for field",
  "errors": [
    "err_reason1",
    "err_reason2"
  ],
  "warnings": []
}
404 Not Found
{
  "status": "alert not found",
  "message": "Failed to update alert"
}

“DELETE”, Delete Alerts

Body Parameters

One of the following IDs is required:

ParameterDescriptionTypeNote
idThe UUID that identifies the alert on the systemstringMandatory if there is not the “unique_identifier” field
unique_identifierAn alert unique identifierstringMandatory if there is not the “id” field

Result Format

200 Ok
{
  "status": "success",
  "message": "Alert deleted successfully"
}
400 Bad Request
{
  "status": "invalid id",
  "message": "Non valid value was received for field",
  "errors": [
      "id =&gt; \"bb56345b-22be-4570-ba08-3320a8821accc\" is not a valid uuid"
  ],
  "warnings": []
}
404 Not Found
{
  "status": "alert not found",
  "message": "Failed to delete alert"
}

“GET”, Query your Alerts

Query Parameters

ParameterDescriptionTypeNote
applicationNameWill check if it contained in the alert’s log_filter.application_name arraystring (case sensitive)
subsystemNameWill check if it contained in the alert’s log_filter.subsystem_name arraystring (case sensitive)
severityQuery by alert’s severitystringMust be one of the following options: [“info”, “warning”, “critical”]
fromTimestampQuery all alerts that have been created from a specific timestamp until nowstring – ISO format
“2020-06-07T17:30:00.000Z”
idQuery by alert’s idstring
uniqueIdentifierQuery by alert’s unique_identifierstring

Note: Pass the query parameters for ‘GET’ request through its URL in the following manner:

<Base API Endpoint>?severity=<severity>&applicationName=<application_name>&subsystemName=<subsystem_name>&fromTimestamp=<YYYY-MM-DDThh:mm:ss.000Z
<Base API Endpoint>?id=<id>
<Base API Endpoint>?uniqueIdentifier=<unique_identifier>

Examples:

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

https://api.coralogix.us/api/v1/external/alerts?id=f3a461d8-21b1-4049-9dd1-9bcdd6b7ad90

https://api.coralogix.us/api/v1/external/alerts?uniqueIdentifier=cecd5e10-a116-11eb-94da-dfa0f95b7fed

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
}
400 Bad Request
{
  "status": "invalid query param",
  "message": "Non valid value was received for field",
  "errors": [ 
    "err_reason1", 
    "err_reason2" 
  ]
}

“GET”, Query Alert Status

Query Parameters

ParameterDescriptionTypeNote
idQuery by alert’s idstring

Note: Pass the query parameters for ‘GET’ request through its URL in the following manner:

<Base API Endpoint>/alert-status/<id>

Example:

https://api.coralogix.com/api/v1/external/alerts/alert-status/0b3d49a2-5291-417e-a30c-83633ce0b35e

The response for this URL will include the current status of your alert.

Response Schema

ParameterDescriptionType
groupsArray of permutation dataARRAY
groupThe fields-values mapOBJECT <String, String>
last_triggered_timestampThe last time the alert was triggeredISODATE
statusThe current status can be resolved/triggeredSTRING

Example

{
	"groups": [
		{
			"group": {
				"serviceName": "frontend"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "productcatalogservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "shippingservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "adservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "paymentservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "cartservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "checkoutservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "currencyservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "loadgenerator"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "featureflagservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "recommendationservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "quoteservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		},
		{
			"group": {
				"serviceName": "emailservice"
			},
			"last_triggered_timestamp": "2023-02-27T08:29:00.000Z",
			"status": "triggered"
		}
	]
}

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]+//

Support

Need help?

Our world-class customer success team is available 24/7 to walk you through your setup and answer any questions that may come up.

Feel free to contact us via our in-app chat or by emailing [email protected].

On this page