SDK API Reference

CrontifyMonitor

The primary class for monitoring a single job.

Constructor

new CrontifyMonitor(options: MonitorOptions)

Option	Type	Required	Default	Description
apiKey	string	✅	—	Your Crontify API key (ck_live_...)
monitorId	string	✅	—	Monitor ID from your dashboard
baseUrl	string		https://api.crontify.com	Override for self-hosted deployments
timeout	number		10000	Request timeout in milliseconds
silent	boolean		true	If true, ping failures are warned, not thrown

---

monitor.start()

monitor.start(): Promise<PingResponse | null>

Signals that the job has started. Creates a run record with status running.

Returns null in silent mode if the ping fails.

---

monitor.success(options?)

monitor.success(options?: SuccessOptions): Promise<PingResponse | null>

Signals successful completion. Closes the run record with status success and records the duration.

Option	Type	Description
meta	Record<string, number>	Numeric metadata stored on the run. Evaluated against any configured alert rules.

await monitor.success({
  meta: {
    rows_processed: 1523,
    emails_sent: 48,
    duration_ms: 3200,
  },
});

Returns null in silent mode if the ping fails.

---

monitor.fail(options?)

monitor.fail(options?: FailOptions): Promise<PingResponse | null>

Signals that the job has failed. Closes the run record with status failed and fires a failure alert immediately.

Option	Type	Description
message	string	Human-readable error message. Included in alert notifications and on the run detail page.
meta	Record<string, number>	Numeric metadata stored on the run.
log	string	Full log output (stdout/stderr). Stored separately. Truncated to 10,000 characters. See Log Attachment.

await monitor.fail({
  message: error.message,
  log: error.stack,
  meta: { exit_code: 1 },
});

Returns null in silent mode if the ping fails.

---

monitor.wrap(fn)

monitor.wrap<T>(fn: () => Promise<T>): Promise<T>

Wraps an async function with automatic start, success, and fail pings. The return value of fn is preserved. Errors are re-thrown after fail() is called.

On error, wrap() automatically captures error.stack as the log field — you get full stack traces in the run detail view with no extra code.

const result = await monitor.wrap(async () => {
  return await fetchAndProcessData();
});
// result is the return value of fetchAndProcessData()

---

CrontifyClient

Manages multiple monitors from a single API key. Monitor instances are cached.

Constructor

new CrontifyClient(options: CrontifyOptions)

Option	Type	Required	Default	Description
apiKey	string	✅	—	Your Crontify API key
baseUrl	string		https://api.crontify.com	Override for self-hosted deployments
timeout	number		10000	Request timeout in milliseconds
silent	boolean		true	Passed to all monitor instances

client.monitor(monitorId)

client.monitor(monitorId: string): CrontifyMonitor

Returns a CrontifyMonitor instance for the given ID. Instances are cached — calling this multiple times with the same ID returns the same object.

---

PingResponse

The response returned by start(), success(), and fail() on success.

interface PingResponse {
  received: boolean;
  monitorId: string;
  runId: string;
  status: string;
  timestamp: string;
}

---

Error types

Importable for use in silent: false mode:

import {
  CrontifyApiError,
  CrontifyTimeoutError,
  CrontifyNetworkError,
} from '@crontify/sdk';

Class	Cause
CrontifyApiError	HTTP 4xx/5xx from the API. Has statusCode and message properties.
CrontifyTimeoutError	Request exceeded the timeout option
CrontifyNetworkError	Connection refused, DNS failure, or other network-level error