Cronitor API

JavaScript SDK

Use the cronitor package to report job runs, heartbeats, and metrics to Cronitor from Node.js, Bun, or Deno.

Install

npm install cronitor

The package runs on servers. It is not for browsers.

Configure

Set the CRONITOR_API_KEY environment variable to your SDK Integration key. Copy the key from Settings → API Keys at https://cronitor.io/app/settings/api. Keep the key in the environment or a secret store of the runtime. Do not commit it.

Call the package without an API key. It then reads CRONITOR_API_KEY:

const cronitor = require('cronitor')();

Monitor a job

cronitor.wrap gives a new function. Call that function to run the job:

const cronitor = require('cronitor')();

const sendInvoices = cronitor.wrap('send-invoices', async () => {
  // the work of the job
});

sendInvoices();
  • Before the function starts, the SDK sends a run event.
  • When the function returns or its promise resolves, the SDK sends a complete event.
  • When the function throws or its promise rejects, the SDK sends a fail event with the error. The wrapper does not throw the error again.
  • Cronitor calculates the duration from the run event and the complete or fail event.
  • The events go to the monitor with the key send-invoices. If no monitor has this key, Cronitor creates one on the first event.

If the function gives a string, the SDK sends it as the message of the complete event.

To monitor jobs that you schedule with node-cron or cron, use cronitor.wraps. See the README.

To send the events yourself, use a Monitor:

const monitor = new cronitor.Monitor('send-invoices');
await monitor.ping({ state: 'run' });
await monitor.ping({ state: 'complete' }); // or state: 'fail'

Send a heartbeat

Send a ping each time the process completes a unit of useful work:

const cronitor = require('cronitor')();

const monitor = new cronitor.Monitor('queue-worker');
monitor.ping({ message: 'Alive!' });

To attach metrics, give a metrics object. The SDK sends each item as metric=name:value. It ignores metrics at the top level, such as { count: 100 }:

monitor.ping({ metrics: { count: 100, error_count: 3 } });

If you only want to record custom metrics, use a heartbeat monitor. See Custom Metrics.

Verify

After one real run, check the state of the monitor. A successful telemetry response shows only that Cronitor received the request. It does not show that Cronitor stored the event or matched it to a monitor.

With the MCP server:

get_status({"key": "send-invoices"})

With CronitorCLI:

cronitor status send-invoices

monitor.ping does not throw. If the request fails, it logs the error and gives false.

Reference

Previous
Python SDK
Next
Ruby SDK