Manage monitors via API

Learn how to manage Axiom monitors via API.

This page explains how to manage monitors programmatically via the API.

Prerequisites

• Create an Axiom account.
• Create a dataset in Axiom where you send your data.

• Create an API token in Axiom with permissions to create, read, update, and delete monitors.
• In the code samples below, replace API_TOKEN with the Axiom API token you have generated. For added security, store the API token in an environment variable.

Create threshold monitors

To create a threshold monitor, send a POST request to the monitors endpoint. In the body of the request, specify the following:

• name of your monitor.
• aplQuery is the APL query that the monitor periodically runs to aggregate data. Axiom alerts you when the results from your query cross the threshold.
• threshold is the value to compare the results of the query to. This can be any numeric value.
• operator is the rule to apply when comparing the results to the threshold. The possible values are Below, BelowOrEqual, Above, and AboveOrEqual.
• intervalMinutes is how often the monitor runs. This is a positive integer number of minutes.
• rangeMinutes is the time range for your query. This is a positive integer number of minutes. The end time is the time the monitor runs.
• alertOnNoData triggers the monitor when your query doesn’t return any data. Your query returns no data if no events match your filters and an aggregation used in the query is undefined. For example, you take the average of a field not present in any matching events.

The following fields are optional:

• description explains what your monitor does.
• notifierIds is a list of notifier IDs. The related notifiers define how you want to receive notifications for this monitor. For more information, see Manage notifiers.
• You can group by attributes when defining your query. By default, your monitor enters the alert state if any of the values returned for the group-by attributes cross the threshold, and remains in the alert state until none of the values returned cross the threshold. To trigger the monitor separately for each group that crosses the threshold, set notifyByGroup to true. At most one trigger notification is sent per monitor run. This option only has an effect if the monitor’s query groups by a non-time field.

For example:

curl -X 'POST' 'https://api.axiom.co/v2/monitors' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN' \
-d '{
    "name": "test_monitor",
    "description": "This is a test monitor.",
    "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
    "threshold": 1,
    "operator": "Above",
    "intervalMinutes": 5,
    "rangeMinutes": 5,
    "notifierIds": ["test_notifier"],
    "alertOnNoData": false
  }'

The example response contains the monitor ID that you can later use to access the monitor programmatically.

{
  "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
  "createdAt": "2024-09-04T13:56:22.222Z",
  "description": "This is a test monitor.",
  "id": "abc123",
  "intervalMinutes": 5,
  "name": "test_monitor",
  "notifierIds": ["test_notifier"],
  "operator": "Above",
  "rangeMinutes": 5,
  "threshold": 1,
  "triggerFromNRuns": 1,
  "type": "Threshold"
}

For more information, see the API reference.

Get information about monitors

Get information about all monitors

To get information about all the monitors in your Axiom organization, send a GET request to the monitors endpoint. For example:

curl -X 'GET' 'https://api.axiom.co/v2/monitors' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

The example response is a list of monitor objects. Each object contains a unique monitor ID that you can later use to access the monitor programmatically.

[
  {
    "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
    "createdAt": "2024-09-04T13:56:22.222Z",
    "description": "This is a test monitor.",
    "id": "abc123",
    "intervalMinutes": 5,
    "name": "test_monitor1",
    "notifierIds": ["test_notifier"],
    "operator": "Above",
    "rangeMinutes": 5,
    "threshold": 1,
    "triggerFromNRuns": 1,
    "type": "Threshold"
  },
  {
    "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
    "createdAt": "2024-09-04T13:56:22.222Z",
    "description": "This is another test monitor.",
    "id": "abc321",
    "intervalMinutes": 5,
    "name": "test_monitor2",
    "notifierIds": ["test_notifier"],
    "operator": "Above",
    "rangeMinutes": 5,
    "threshold": 1,
    "triggerFromNRuns": 1,
    "type": "Threshold"
  }
]

For more information, see the API reference.

Get information about specific monitor

To get information about a specific monitor, send a GET request to the monitors/ID endpoint where ID is the unique ID of the monitor. For example:

curl -X 'GET' 'https://api.axiom.co/v2/monitors/abc123' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

Example response:

{
  "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
  "createdAt": "2024-09-04T13:56:22.222Z",
  "description": "This is a test monitor.",
  "id": "abc123",
  "intervalMinutes": 5,
  "name": "test_monitor",
  "notifierIds": ["test_notifier"],
  "operator": "Above",
  "rangeMinutes": 5,
  "threshold": 1,
  "triggerFromNRuns": 1,
  "type": "Threshold"
}

For more information, see the API reference.

Update monitors

To update a monitor, send a PUT request to the monitors/ID endpoint where ID is the unique ID of the monitor. In the body of the request, specify the properties you want to update. For example:

curl -X 'PUT' 'https://api.axiom.co/v2/monitors/abc123' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN' \
-d '{
    "name": "test_monitor",
    "description": "This is a production monitor.",
    "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
    "threshold": 1,
    "operator": "Above",
    "intervalMinutes": 5,
    "rangeMinutes": 5,
    "notifierIds": ["test_notifier"],
    "alertOnNoData": false
  }'

Example response:

{
  "aplQuery": "test_dataset | summarize count() by bin_auto(_time)",
  "createdAt": "2024-09-04T13:56:22.222Z",
  "description": "This is a production monitor.",
  "id": "abc123",
  "intervalMinutes": 5,
  "name": "test_monitor",
  "notifierIds": ["test_notifier"],
  "operator": "Above",
  "rangeMinutes": 5,
  "threshold": 1,
  "triggerFromNRuns": 1,
  "type": "Threshold"
}

For more information, see the API reference.

Delete monitors

To delete a monitor, send a DELETE request to the monitors/ID endpoint where ID is the unique ID of the monitor. For example:

curl -X 'DELETE' 'https://api.axiom.co/v2/monitors/abc123' \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer API_TOKEN'

For more information, see the API reference.