The heart of the CronAlarm system is the API. We offer a simple API that is available to all plans, and an advanced API that is available for the Professional and Enterprise plans.

Since every job in the CronAlarm system is assigned a unique API key, you'll need that information before you can call the API. For more information about managing your jobs and API keys, see our Jobs documentation. For the examples on this page, we'll assume our API key is "12345".

The API works by calling a URL at the beginning of your job and then again at the end. From this information, at a minimum the CronAlarm platform will be able to monitor when your job last ran, and how long it took to complete it's task. The difference between the simple and advanced API is that what additional information, if any, can be reported from by you.

If your only concern is when your job runs and how long it takes to run, the simple API is all you need. The simple API consists of 2 GET requests. Here is a quick example (again, let's assume our API key is "12345"):

curl https://api.cronalarm.com/v2/12345/start
# do your stuff here
curl https://api.cronalarm.com/v2/12345/end

As you can see, the API url follows the following format: https://api.cronalarm.com/v2/<your api key>/(start|end). You'll want to call the /start API url at the beginning for your job, and the /end API url at the end of your job.

With just those 2 lines of code added to your job, CronAlarm will be able to determine when your job ran, and how long it took to run. CronAlarm will then compare the results to any metrics you've defined for runtime alerts, and if anything outside of your settings is detected, CronAlarm will send alerts.

Some users find the simple API sufficient for their needs. However, CronAlarm also offers an advanced API that allows you to take your cron monitoring up a notch.

Here is how it's done. You start out with a simple GET request just like you did in the simple API example:

curl https://api.cronalarm.com/v2/12345/start
# do your stuff here

So far, so good, right? This time, however, at the end of your code you can do a POST request to the CronAlarm API and send in some additional information. The API takes 4 arguments (all are optional, so you only need to use what you want):

• success - This is your own 'success' status and can be either a 1 (true) or 0 (false). Your cron job will most likely have multiple steps (for example - write information to a file, open an FTP connection, send the file, delete the local copy, etc) and you may already be utilizing some try/catch techniques to get through it. CronAlarm's advanced API allows you to leverage your existing error handling in reporting the success status. Keep in mind, however, that even if you report a successful completion of your job, but the execution time falls outside the parameters you specified, the job will be recorded as an error and you will still receive alerts.
• message - Your custom message. Did your job fail when opening an FTP connection to a remote server? Then send a message saying so. In the error report you receive you'll know exactly what the problem was so you'll know right away what action to take.
• server - The name or IP address of the server where the job was executed. You may have multiple servers in your organization and you may have cron jobs across some (or even all) of them. Report your server name or IP address to CronAlarm and you'll know right away where to begin troubleshooting when an error occurs.
• path - The file system path to the file that was executed. If you send the 'server' parameter, you'll already know which server to look at, now you'll know where the cron job is being run from. Again, this is incredibly helpful information to have if you support multiple server and locations.

Below is an example of accessing the advanced API to report an error:

curl -X POST -H 'Content-type: application/json' --data '{"success": "0", "server": "webserver1", "path": "/var/www/ftptransfer.js", "message": "failure to connect to remote server"}' https://api.cronalarm.com/v2/12345/end

Getting an error report that tells you the job called 'file transfer' failed is nice. But getting an error report that tells you job 'file transfer' failed on server 'webserver1' located at '/var/www/ftptransfer.js' is pretty cool and much more helpful. If you manage jobs that run on multiple servers you'll really appreciate this additional information.

The CronAlarm API will return standard HTTP response codes to indicate the status of you request. You can use these response codes to help troubleshoot any issues you may be having on your end.

• 200 - Request completed successfully.
• 403 - Your account is not active, or you do not have access to the API (for example, you tried to use the advanced API but your plan does not include the advanced API).
• 404 - You either attempted to access the wrong URL for the API, or used an invalid API key.
• 500 - A server-side error.