Cron Job Monitoring API

Cron Job Monitoring API

Receive alerts when your cron jobs and scheduled tasks don't run on time. Simple and effective monitoring for your scheduled tasks.
Free Plan $0.00 Monthly Subscribe
300 Requests / Monthly
Free for Lifetime
No Credit Card Required
MOST POPULAR
Starter Plan $4.99 Monthly Subscribe
30,000 Requests / Monthly
Standard Support
Fast and reliable
Affordable
Pro Plan $29.99 Monthly Subscribe
3,000,000 Requests / Monthly
Standard Support
Fast and reliable
Affordable
Custom Plan Volume Monthly Contact Us
Any requests volume you need
Fast and reliable
Affordable

Monitoring cron jobs is as difficult as it is important. Because these tasks usually run on servers that are not accessible from outside HTTP calls, and the only way to get information from them is cron jobs sending logs itself to another service.

The Cron Job Monitoring API does exactly that. Every time your services are running, they report that they are OK or there is a problem, via a ping event to this API. If your service is delayed in sending pings until grace time, Cron Job Monitoring API will notify you immediately by e-mail. It's that simple!

Let's start using it step by step

1. Create a new "check"

We start using the API by creating a new check. Don't forget to give it a beautiful and memorable name. POST /check endpoint will create a new check and give you a unique "ping url" back. The next step should be for your application to start pinging this ping url.

curl --location \
--request POST 'https://api.apilayer.com/cron_monitoring/check' \
--header 'apikey: API KEY' \
--data-raw 'My First Check'

When a new check is created all of it information is returned with the response

{
    "id": "5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b",
    "name": "My First Check",
    "status": "unknown",
    "ping_url": "https://api.apilayer.com/cron_monitoring/p/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b",
    "schedule": {
        "type": "cron",
        "cron_expression": "0 * * * *",
        "grace_time": 60,
        "timezone": "UTC",
        "last_check_at": null,
        "cron_description": "Every hour"
    },
    "integrations": [
        {
            "type": "email",
            "email": "[email protected]",
            "owner": "[email protected]"
        }
    ]
}
2. Pinging the API regularly

Place the following piece of code in your cron jobs that pinging for this check wherever you see fit. You can put as often as you want. It can also happen inside a for loop, only 1 time. It's entirely up to you. The Cron Job Monitoring API will store the last 1000 ping requests for you, and you can get the whole ping list with GET / check / / pings endpoint.

curl --location \
--request POST 'https://api.apilayer.com/cron_monitoring/ping/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b' \
--header 'apikey: API KEY' \
--data-raw 'This is some description'
3. Pinging for special statuses

If you want to notify the API that the application has a problem somewhere, simply add / fail to the end of your ping_url and send it. You can also send / start and / finish status codes. Messages sent with / fail status will intelligently shorten the grace time and allow you to receive earlier alerts if the cron is delayed.

curl --location \
--request POST 'https://api.apilayer.com/cron_monitoring/ping/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b/fail' \
--header 'apikey: API KEY' \
--data-raw 'This is the ping description.'
4. Getting the ping information

You can get the description of your check and how often it will check the service with GET / check / endpoint. Your API will look for any ping at the times specified in the cron expression, then wait for the time specified by grace time. If there is still no ping, it will alert you.

curl --location \
--request GET 'https://api.apilayer.com/cron_monitoring/check/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b' \
--header 'apikey: API KEY'
5. Retrieving the logs for a check

If you want to view all "pings" at once, you can use the GET / pings endpoint.

curl --location \
--request GET 'https://api.apilayer.com/cron_monitoring/check/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b/pings' \
--header 'apikey: API KEY'
6. Settting the crontab expression

By default, your API will set the crontab expression to 0 * * * * once a day. If you want to change this, you can use the PUT / schedule / cron endpoint.

curl --location \
--request PUT 'https://api.apilayer.com/cron_monitoring/check/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b/schedule/cron' \
--header 'apikey: API KEY' \
--data-raw '0 */3 * * *'
7. Updating the grace time

Your API takes grace time 60 minutes by default. If you want to change this value PUT / schedule / grace.

curl --location \
--request PUT 'https://api.apilayer.com/cron_monitoring/check/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b/schedule/grace' \
--header 'apikey: API KEY' \
--data-raw '90'
8. Changing the timezone/

The API will take UTC as the default timezone. If you want to change it, you can use the PUT / schedule / timezone endpoint.

curl --location \
--request PUT 'https://api.apilayer.com/cron_monitoring/check/5dfaf9d0-3a2c-40dd-902e-cc0fb352b86b/schedule/timezone' \
--header 'apikey: API KEY' \
--data-raw 'UTC+04:00'

That is all! This information covers the basics of your API. You can find more details in the API documentation.

Cron Job Monitoring API Reference

This API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.

Just Getting Started?

Check out our development quickstart guide.

Authentication

Cron Job Monitoring API uses API keys to authenticate requests. You can view and manage your API keys in the Accounts page.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

All requests made to the API must hold a custom HTTP header named "apikey". Implementation differs with each programming language. Below are some samples.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

Endpoints

Deletes a check and all its ping history. Be careful with this. This operation can't be undone.

Parameters

check_id (required)

id of the check to delete

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Returns all the information bound with this check.

Parameters

check_id (required)

id of the check to retrieve its info

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Parameters

check_id (required)

id of the check to fetch its schedule

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Returns the schedule for this check. Cron expression, grace time and timezone values will be included.

Parameters

check_id (required)

id of the check to fetch its schedule

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Retrieves all the checks currently available

Parameters
No parameters.
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Creates a new check and return a new unique ping url.

Parameters

body (required)

Name of the new check

Location: Body, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Shortcut for pinging the check with a success status. Same as running /ping//success

Parameters

check_id (required)

id of the check to ping

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Pings the check. This is the endpoint to send signals from your Cron job.

Parameters

check_id (required)

id of the check to ping

Location: Path, Data Type: string

status (required)

status for ping. Possible values: start, success, fail or finish)

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Updates the human readable name value of a check.

Parameters

body (required)

New name for this check

Location: Body, Data Type: string

check_id (required)

id of the check to retrieve its info

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Updates the alert email address. When a check is late and grace time has exceeded, an alert will be sent to this e-mail address.

Parameters

body (required)

Email address for alert

Location: Body, Data Type: string

check_id (required)

id of the check to update its name

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Updates the crontab expression for a check.

Parameters

body (required)

New Crontab expression

Location: Body, Data Type: string

check_id (required)

id of the check to fetch its schedule

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Updates the timezone for a check.

Parameters

body (required)

New timezone (defaults to UTC)

Location: Body, Data Type: string

check_id (required)

id of the check to update its timezone

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Updates the grace time for a check

Parameters

body (required)

New grace time (in minutes)

Location: Body, Data Type: integer

check_id (required)

id of the check to fetch its schedule

Location: Path, Data Type: string

** A word enclosed with curly brackets "{ }" in the code means that it is a parameter and it should be replaced with your own values when executing. (also overwriting the curly brackets).
Returns

Below is a sample response from the endpoint


If you wish to play around interactively with real values and run code, see...

Rate Limiting

Each subscription has its own rate limit. When you become a member, you start by choosing a rate limit that suits your usage needs. Do not worry; You can upgrade or downgrade your plan at any time. For this reason, instead of starting with a larger plan that you do not need, we can offer you to upgrade your plan after you start with "free" or "gold plan" options and start using the API.

When you reach a rate limit (both daily and monthly), the service will stop responding and returning the HTTP 429 response status code (Too many requests) for each request with the following JSON string body text.

{
"message":"You have exceeded your daily\/monthly API rate limit. Please review and upgrade your subscription plan at https:\/\/apilayer.com\/subscriptions to continue."
}

A reminder email will be sent to you when your API usage reaches both 80% and 90%, so that you can take immediate actions such as upgrading your plan in order to prevent your application using the API from being interrupted.

You can also programmatically check your rate limit yourself. As a result of each request made to the APILayer, the following 4 fields provide you with all the necessary information within the HTTP Headers.

x-ratelimit-limit-month: Request limit per month
x-ratelimit-remaining-month: Request limit remaining this month
x-ratelimit-limit-day: Request limit per day
x-ratelimit-remaining-day: Request limit remaining today

You can contact our support unit if you need any assistance with your application regarding to handle the returned result by looking at the header information.

Error Codes

APILayer uses standard HTTP response codes to indicate the success or failure of an API request. In general: Codes in the 2xx range indicate success. Codes in the 4xx range indicate a clientside error, which means that failed given the information provided (e.g., a missing parameter, unauthorized access etc.). Codes in the 5xx range indicate an error with APILayer's servers (normally this should'nt happen at all).

If the response code is not 200, it means the operation failed somehow and you may need to take an action accordingly. You can check the response (which will be in JSON format) for a field called 'message' that briefly explains the error reported.

Status Code Explanation
400 - Bad Request The request was unacceptable, often due to missing a required parameter.
401 - Unauthorized No valid API key provided.
404 - Not Found The requested resource doesn't exist.
429 - Too many requests API request limit exceeded. See section Rate Limiting for more info.
5xx - Server Error We have failed to process your request. (You can contact us anytime)

You can always contact for support and ask for more assistance. We'll be glad to assist you with building your product.