API Docs

Monitor API


The Monitor API allows you to configure monitor settings, including schedules, assertions, alert preferences and more.

This guide includes a detailed reference of monitor attributes, as well as examples of creating, modifying, and deleting a monitor. Cronitor's open-source SDKs are the easiest way to use this API.

In this guide:

Monitor Attributes

assertions array containing strings optional

Monitors are continuously evaluated for both schedule and assertion violations. When Cronitor detects a problem, an alert is sent.

The syntax for expressing most assertions is:

  • "{assertion} {operator} {value}"
  • "metric.duration < 5 min"
  • "response.code = 200"

Assertions that use an access key to a hash data structure — response.json and response.header assertions — are expressed as:

  • "{assertion_name} {key} {operator} {value}"
  • "response.json new_user.count > 10"
  • "response.header X-App-Version = 1.2.3"
Assertion Monitor Type Operators Value Type
metric.duration job, event <, <=, >=, > interval e.g. '2 minutes'
metric.count job, event <, <=, >=, > int
metric.error_count job, event <, <=, >=, > int
metric.error_rate job, event <, <=, >=, > decimal
response.time check <, <=, >=, > interval e.g. '1.2s'
response.code check <, <=, >=, > int
response.body check contains, !contains, =, != string
response.json check contains, !contains, <, <=, =, !=, >=, > *
response.header check contains, !contains, <, <=, =, !=, >=, > *
resource.last_modified check <, <=, =, !=, >=, > interval
resource.item_count check <, <=, =, !=, >=, > int
resource.public check = boolean
grace_seconds integer default: 60 for type 'job', 0 for types 'event'/'check'

The number of seconds that Cronitor should wait after detecting a failure before dispatching an alert. If the monitor recovers during the grace period no alert will be sent.

group string optional

Groups are user-defined collections of monitors, that are used to group monitors in the Cronitor application. Each group has a unique URL with the format https://cronitor.io/app/groups/:groupKey

key string required

A monitor’s unique identifier. The key is used in making API requests to an individual monitor resource, e.g. https://cronitor.io/api/monitors/:monitorKey

It is also the required identifier for sending telemetry events. https://cronitor.link/ping/API_KEY/:monitorKey

metadata hash optional

A JSON serializable set of arbitrary key/value pairs that contain useful information about a job. For example, cronitor-kubernetes stores fields like backoffLimit and startingDeadlineSeconds.

name string default: 'key' attribute

The display name of this monitor. Used to identify your monitor in alerts and within the Cronitor application.

note string optional

A useful place to provide additional context/troubleshooting information about the job/system being monitored. The note is sent in alerts (excluding SMS), and are accessible from the monitor details view in the Cronitor application.

notify mixed type: array, hash default: ['default']

Configure where alerts sent when Cronitor detects an error. Additionally, notify can be used to specify occurrence based alerts - alerts based on receiving telemetry pings.

All accounts have a default Notification List (key="default"). If notify is left empty or omitted, the default list will be used.

Array: An array of Notification List keys. Notification Lists are used for configuring how alerts are sent to your team.

"notify": [‘devops-channel’]

Hash: To specify separate notification preferences a hash containing the keys "alerts" and "events" can be used.

The "alerts" key accepts an array of Notification List keys. The "events" key accepts a hash with keys corresponding to the lifecycle telemetry events - run, complete. If these keys are set to true, Cronitor will send a notification when the event occurs.

{ "notify": { "alerts": [‘foo-bar’], "events": {"complete": true} }

platform string optional / type dependent

The platform attribute is used in conjunction with the type attribute to tell Cronitor about where and how a monitor is being run beyond.

The platform options for job monitors are:

  • cron (default)
  • windows
  • kubernetes
  • jvm
  • laravel
  • magento
  • sidekiq
  • celery
  • jenkins
  • quartz
  • spring
  • cloudwatch
  • node-cron

The platform options for check monitors are:

  • http (default)
  • browser (executes javascript)
  • tcp
  • udp
  • s3
realert_interval integer or string optional default: '8 hours'

Interval expression telling Cronitor how long to wait before sending follow up alerts after a monitor fails (and does not recover).

If an integer is provided it will be interpreted as `X hours`

After 10 alerts, Cronitor will mute alerting until the monitor recovers.

request hash required by type 'check'

The details of the outgoing request:

  • url string - The URL of the resource to monitor.
  • method string - The HTTP request method: GET HEAD PATCH POST PUT
  • body string - The request body. Required for PUT, PATCH, and POST requests.
  • headers hash optional - The HTTP headers of the request (e.g. User-Agent). Limited to 5120 chars.
  • cookies hash optional - Cookies to set before each request. Limited to 5120 chars.
  • timeout_seconds integer 1 to 15 default: 10 - The timeout enforced when making the request. An alert will be triggered upon timeout.

schedule string optional

Schedule has different meanings depending on the monitor type.

job & event: the schedule tells Cronitor when to expect telemetry events from your system. If events are not received on schedule, an alert is sent.

An interval expression (‘every 5 minutes’) or a cron expression (‘0 0 * * *’) must be used.

check: the schedule is used to tell Cronitor how frequently to make requests to the resource being monitored.

An interval expression must be used. The range of accepted values is 30 seconds to 1 hour. e.g. ‘every 2 minutes’.

tags array of strings optional

Tags are user provided strings that can be used to associate and filter monitors in the Cronitor dashboard. Use tags however you would like.

timezone string default: account.timezone or 'UTC'

The timezone your system is running in.

schedule_tolerance integer default: 0

Number of missed scheduled executions to allow before sending an alert.

failure_tolerance integer default: 0

job & event: number of telemetry events with state='fail' to allow before sending an alert.

check: number of consecutive failed requests allow before sending an alert.

type string enum(job|event|check) required

The type attribute determines which of Cronitor's monitoring capabilities are used to assess the health of your system. Based on the type provided, other attributes may be required — e.g. the checks type requires the request attribute to be set.

jobs monitor the execution of a backend job (cron job, windows scheduled task, etc). This involves tracking the lifecycle of the job - the start_time, end_time and exit_state of the job.

events monitor the health of a system via telemetry events. There is no lifecycle to measure, the occurrence (or absence) of healthy/unhealthy events, as well as data passed as custom metrics are used to determine the health of an event monitor.

checks monitor websites, APIs, proxy servers, cloud storage providers (e.g. S3) or any other HTTP/TCP/UDP networked device.

Read Only Attributes

created timestamp

ISO 8601 formatted timestamp of when the monitor was created.

disabled boolean

Whether the monitor is currently disabled.

initialized boolean

Whether the monitor has received a telemetry event.

passing boolean

Whether the monitor is currently passing or failing.

paused boolean

Whether sending alerts is currently paused.

running boolean

Whether a job is running (only applicable for type: job).

Advanced Attributes

defaultName string

When using Cronitor as part of a provisioning process it is useful to provide a name, but to allow users to be able to later edit that name from the Cronitor dashboard without the provisioning script later replacing the edit.

defaultName will be displayed as the name attribute if name is not set.

defaultNote string

Same as defaultNote above, but for the note field.

Creating Monitors

The Monitor API supports bulk creates (and updates) by making a PUT request to the top level monitors resource. 

PUT https://cronitor.io/api/monitors   |   status_codes: 200, 400
curl --user API_KEY: \
--header "Content-Type: application/json" \
--request PUT \
--data '{
        "monitors": [
            {
                "type": "job",
                "key": "nightly-backup-job",
                "schedule": "0 0 * * *",
                "notify": ["devops-alerts"],
                "assertions": ["metric.duration < 15min"]
            },
            {
                "type": "job",
                "key": "weekly-customer-reports",
                "schedule": "0 0 * * Mon",
                "notify": ["devops-alerts"],
                "assertions": ["metric.duration < 30s"]
            }
        ]
    }' \
https://cronitor.io/api/monitors

Tip:The body of a PUT request can be an array of monitors (shown above), or a hash containing the keys "monitors" (array) and "rollback" (boolean) — a flag that will run the request in a transaction that is rolled back on success. This can be helpful when testing/validating monitor configuration.

Monitors can also be created individually by making a POST request. 

POST https://cronitor.io/api/monitors   |   status_codes: 201, 400
 // create a job monitor
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "type": "job",
        "key": "nightly-backup-job",
        "schedule": "0 0 * * *",
        "notify": ["devops-alerts"]
    }' \
https://cronitor.io/api/monitors

// create a check monitor
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request POST \
    --data '{
        "type": "check",
        "key": "cronitor-homepage",
        "schedule": "every 60 seconds",
        "notify": ["uptime-alerts"],
        "request": {
            "url": "https://cronitor.io",
            "regions": ["us-east-1", "eu-central-1", "ap-south-1"]
        }
    }' \
https://cronitor.io/api/monitors

Retrieving Monitors

Monitors can be retrieved in bulk by making a GET request to the top level monitors resource.

GET https://cronitor.io/api/monitors
curl https://cronitor.io/api/monitors -u API_KEY:

An individual monitor can be retrieved by making a GET request that includes a monitor key in the URL. 

GET https://cronitor.io/api/monitors/:monitorKey
curl https://cronitor.io/api/monitors/nightly-backup-job -u API_KEY:

Updating Monitors

Monitors can be modified in bulk by issuing a PUT request to the top level monitors resource:

PUT https://cronitor.io/api/monitors   |   status_codes: 200, 400
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    -d '{
        "monitors": [
            {
                "schedule": "0 1 * * *",
                "key": "nightly-backup-job"
            },
            {
                "schedule": "5 * * * *",
                "key": "hourly-report-generator"
            }
        ]}' \
https://cronitor.io/api/monitors

Monitors can be modified indivually by making a PUT request that includes a monitor key in the URL.

PUT https://cronitor.io/api/monitors/:monitorKey   |   status_codes: 200, 400
curl --user API_KEY: \
    --header "Content-Type: application/json" \
    --request PUT \
    --data '{
        "schedule": "0 1 * * *",
    }' \
    https://cronitor.io/api/monitors/nightly-backup/job

Deleting Monitors

Monitors can be modified indivually by making a DELETE request that includes a monitor key in the URL.

DELETE https://cronitor.io/api/monitors/:monitorKey
curl -X DELETE https://cronitor.io/api/monitors/nightly-backup-job -u API_KEY:

Pausing Monitors

You can programatically pause the evaluation of a monitor. When a monitor is in a paused state Cronitor will record and display all telemetry events, but will not dispatch alerts if a schedule or assertion violation is detected. 

GET https://cronitor.io/api/monitors/:monitorKey/pause
// pause monitoring indefinitely
GET https://cronitor.io/api/monitors/:monitorKey/pause/24
// pause monitoring for 24 hours
GET https://cronitor.io/api/monitors/:monitorKey/pause/0
// resume monitoring