API Reference

This page documents every public function exported by the node-cron module. For conceptual guides, follow the links into Task Lifecycle, Scheduling Options, and Events.

import cron, {
  schedule,
  createTask,
  validate,
  validateDetailed,
  parse,
  getTasks,
  getTask,
  setLogger,
  setRunCoordinator,
} from 'node-cron';

Both the default export (cron.schedule(...)) and named exports (schedule(...)) are available.

schedule(expression, func, options?)

Creates a task and starts it immediately. Returns a ScheduledTask.

Parameters

Name	Type	Description
expression	string	A valid cron expression (e.g. "0 0 * * *" for daily at midnight).
func	Function | string	A function to run, or a path to a module exporting a task function. A path creates a Background Task.
options	Options (optional)	Execution options. See Scheduling Options.

Options

type Options = {
  name?: string;                  // human-readable identifier
  timezone?: string;              // e.g. "America/New_York"
  noOverlap?: boolean;            // skip a run if the previous one is still going
  maxExecutions?: number;         // destroy the task after N runs
  maxRandomDelay?: number;        // jitter, in ms, added before each run
  logger?: Logger;                // per-task logger (not for background tasks)
  suppressMissedWarning?: boolean // silence the "missed execution" warning
  missedExecutionTolerance?: number // ms a late run may still execute (default 1000)
  distributed?: boolean;          // run on one instance per fire across a fleet
  runCoordinator?: RunCoordinator;// per-task coordinator (overrides the global one)
  distributedLease?: number;        // lease ms for lease-based coordinators (default 30000)
};

Background tasks accept two extra options, executeTimeout and startTimeout, documented in Background Tasks.

See Scheduling Options for details and examples.

Returns

A ScheduledTask with control methods:

import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});

task.stop();    // pause the task
task.start();   // start or resume it
task.destroy(); // remove it permanently

🛈 For inline tasks these methods are synchronous (void); for background tasks they return a Promise. See Task Lifecycle.

createTask(expression, func, options?)

Same as schedule, but does not start the task; it's returned in the stopped state. Useful when you need to attach event listeners first, start conditionally, or control timing in tests.

import cron from 'node-cron';

const task = cron.createTask('0 * * * *', () => {
  console.log('Running every hour');
});

task.start();

validate(expression)

Returns true if the cron expression is syntactically valid, false otherwise.

import cron from 'node-cron';

cron.validate('0 12 * * *'); // true
cron.validate('invalid');    // false

validateDetailed(expression)

Like validate, but instead of a boolean returns a structured result describing every problem (which field, the offending value, and why). Useful for tooling, editors, and richer error messages.

type CronFieldError = { field: string; value?: string; message: string };
type DetailedValidation = {
  valid: boolean;
  fields?: ParsedFields;   // present only when valid
  errors: CronFieldError[];
};

import { validateDetailed } from 'node-cron';

validateDetailed('0 12 * * *');
// { valid: true, errors: [], fields: { second: [0], minute: [0], hour: [12], ... } }

validateDetailed('99 12 * * 9');
// {
//   valid: false,
//   errors: [
//     { field: 'minute',    value: '99', message: '99 is a invalid expression for minute' },
//     { field: 'dayOfWeek', value: '9',  message: '9 is a invalid expression for week day' },
//   ]
// }

It reports every bad field at once (not just the first). See Cron Syntax.

parse(expression)

Parses a cron expression into its decomposed, expanded fields, or throws an Error describing the first invalid field.

type ParsedFields = {
  second: number[];
  minute: number[];
  hour: number[];
  dayOfMonth: (number | string)[];
  month: number[];
  dayOfWeek: number[];
};

import { parse } from 'node-cron';

parse('0 12 * * 1-5');
// { second: [0], minute: [0], hour: [12], dayOfMonth: [1, …, 31], month: [1, …, 12], dayOfWeek: [1, 2, 3, 4, 5] }

parse('0 99 * * *'); // throws: 99 is a invalid expression for hour

Use parse when you want the structured fields (or a thrown error); use validate for a boolean and validateDetailed for a non-throwing list of problems.

getTasks()

Returns a Map<string, ScheduledTask> of every task currently registered by node-cron, keyed by task id. Tasks created with schedule or createTask are registered automatically, and a destroyed task removes itself from the registry. Useful for inspection, dashboards, or shutting everything down.

import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {
  console.log('Running every minute');
});

const tasks = cron.getTasks();

console.log(tasks.has(task.id));          // true
console.log(tasks.get(task.id) === task); // true

You can also iterate the map directly:

import cron from 'node-cron';

for (const [id, task] of cron.getTasks()) {
  console.log(id, task.name, task.getStatus());
}

getTask(id)

Returns the registered ScheduledTask with the given id, or undefined when no task exists for that id.

import cron from 'node-cron';

const task = cron.schedule('* * * * *', () => {});

const sameTask = cron.getTask(task.id); // === task
sameTask?.stop();

setLogger(logger)

Replaces the global logger node-cron uses for its internal messages (such as the missed-execution warning), routing them through your own logger.

import { setLogger } from 'node-cron';

setLogger({
  info:  (msg) => myLogger.info(msg),
  warn:  (msg) => myLogger.warn(msg),
  error: (msg, err) => myLogger.error(err ?? msg),
  debug: (msg) => myLogger.debug(msg),
});

The argument is any object implementing the Logger interface (info, warn, error, debug). See the Logging guide for the full interface, per-task loggers, winston/pino adapters, and the missed-execution warning.

setRunCoordinator(coordinator)

Sets the process-wide run coordinator used by tasks scheduled with distributed: true. This is the high-availability path: any instance can run a fire, only one wins. Without it, distributed tasks fall back to the NODE_CRON_RUN env-var default (a single designated runner).

import { setRunCoordinator } from 'node-cron';
import { RedisLockCoordinator } from '@node-cron/redis-coordinator';

setRunCoordinator(new RedisLockCoordinator(redis));

The argument is any object implementing the RunCoordinator interface:

interface RunCoordinator {
  shouldRun(key: string, ttlMs: number): boolean | Promise<boolean>;
  onComplete?(key: string): void | Promise<void>;
}

Pass undefined to clear it. A per-task coordinator can be set via the runCoordinator option. See Distributed Coordination for the full guide.

Next steps

• Task Lifecycle & Status: what the returned task can do.
• Migrating from v3: if you're upgrading an existing project.