Heroku Scheduler Weekly Jobs and Other Custom Intervals

Heroku Scheduler gives a job three frequencies: every 10 minutes, every hour, or every day. Most jobs fit one of them. Then you need a digest that goes out every Monday, an invoice run on the first of the month, or a sync every 3 hours, and Heroku Scheduler supports none of those schedules.

You don't need a different scheduler for that. Developers have used the same trick for years: schedule the job on the Heroku Scheduler frequency that your schedule is a multiple of, and make the job's first step a check that decides whether this run does the work. A Heroku Scheduler weekly job becomes a daily job that exits right away on six days out of seven.

It takes a few lines of code and no extra dyno, and it suits any job that can live with a rare missed or doubled run. The same check covers monthly and every-few-hours jobs too.

Step 1: Pick the frequency your schedule is a multiple of

Use the longest Heroku Scheduler frequency that still lands on every run you want. For a weekly or monthly job that's every day, and for a job every few hours it's every hour. You could check everything from the 10-minute frequency, but the frequency also sets how long each run may take: a dyno started by Heroku Scheduler doesn't run longer than its scheduling interval. A monthly job on the 10-minute frequency gets up to 10 minutes to do a month of work, while on the daily frequency it gets up to 24 hours. It also starts just 30 dynos a month instead of about 4,320, and each one counts toward your dyno usage.

Schedule you want Heroku Scheduler frequency The job's check Time each run gets
Weekly, on Monday Every day Is it Monday? Up to 24 hours
Weekdays only Every day Is it Monday to Friday? Up to 24 hours
Monthly, on the 1st Every day Is it the 1st? Up to 24 hours
Every 2, 3, 4, 6, or 8 hours Every hour Does the hour divide by 2, 3, 4, 6, or 8? Up to 1 hour

Some schedules need no check at all. An hourly job runs at the minute past the hour you choose, as in the Dev Center example of an hourly job at ":30", so every 30 minutes is two hourly jobs with the same command, one at :00 and one at :30. A schedule that isn't a multiple of 10 minutes, such as every 15 or 45 minutes, can't be built from these three frequencies, check or not.

Step 2: Add a check that exits when the weekly job isn't due

Put the check at the very top of the job, before it loads or connects to anything, so a run that isn't due costs as little as possible. This Node.js job sends a weekly digest on Mondays:

// bin/weekly-digest.mjs, scheduled daily: node bin/weekly-digest.mjs
const now = new Date();
const isDue = now.getUTCDay() === 1; // Monday, in UTC

if (!isDue) {
  console.log(`Not due: the weekly digest runs on Mondays (UTC), it is day ${now.getUTCDay()}`);
  process.exit(0);
}

console.log("Due: sending the weekly digest");
const { sendWeeklyDigest } = await import("../lib/digest.js");
await sendWeeklyDigest(); // if it throws, Node.js exits with status 1

Two details make this work in production. The run that isn't due exits with status 0, because skipping is the job doing its job, not a failure. And it logs one line saying so, which is how you tell a quiet day from a job that never ran.

The other schedules from Step 1 change only the isDue line:

// Weekdays only, on the daily frequency
const isDue = now.getUTCDay() >= 1 && now.getUTCDay() <= 5;

// Monthly on the 1st, on the daily frequency
const isDue = now.getUTCDate() === 1;

// Every 3 hours (00:00, 03:00, 06:00 UTC, and so on), on the hourly frequency
const isDue = now.getUTCHours() % 3 === 0;

Step 3: Schedule the job and read its first run

Add the job as a daily job at 00:00 UTC, and after its first run, confirm that it logged its check and exited with status 0. Open the Heroku Scheduler dashboard and click Add Job:

# Open the Heroku Scheduler dashboard in your browser
$ heroku addons:open scheduler --app example-app

Enter node bin/weekly-digest.mjs as the command, choose Daily, and pick 00:00. For an every-few-hours job, choose Hourly and pick :00 instead. Save the job, and after its first run, read that run's lines by the dyno name Heroku Scheduler gave it. A run on a day that isn't Monday looks like this example:

# Show the lines of one Heroku Scheduler run
$ heroku logs --dyno-name scheduler.1234 --app example-app
2026-10-20T00:00:04.101234+00:00 heroku[scheduler.1234]: Starting process with command `node bin/weekly-digest.mjs`
2026-10-20T00:00:04.701234+00:00 heroku[scheduler.1234]: State changed from starting to up
2026-10-20T00:00:05.301234+00:00 app[scheduler.1234]: Not due: the weekly digest runs on Mondays (UTC), it is day 2
2026-10-20T00:00:05.401234+00:00 heroku[scheduler.1234]: Process exited with status 0
2026-10-20T00:00:05.411234+00:00 heroku[scheduler.1234]: State changed from up to complete

The Not due line followed by Process exited with status 0 is the check working: the run started, saw a Tuesday, and stopped without touching the digest. On Monday the same job logs Due: sending the weekly digest, followed by whatever the digest itself writes.

Two things to keep in mind

A check decides which runs do the work, but it can't make Heroku Scheduler more reliable than it is. Heroku Scheduler is a free add-on with no guarantee that jobs will execute at their scheduled time, or at all, and a job behind a check feels that more than most. If Heroku Scheduler skips the run on the 1st, which happens rarely, the monthly invoice run waits until the 1st of the next month. Weigh that before you run a monthly job your business depends on with this setup.

Time zones are the other catch. Heroku Scheduler sets a daily job's run time in UTC, and UTC doesn't change for daylight saving time, so a job at 00:00 UTC moves by an hour on your local clock twice a year. If the schedule has to follow a local clock, say "every Monday at 9:00 AM in Amsterdam", our Advanced Scheduler add-on runs tasks from cron expressions, with a time zone per trigger.

Where Heroku Scheduler Monitor fits

Heroku Scheduler Monitor covers what the check can't. When Heroku Scheduler skips a run, the add-on notices and alerts you by email, so a missed invoice run on the 1st doesn't go unnoticed for a month. Its Job Failure and other monitors watch the runs that do start.

You install the add-on in a few clicks, and it needs no configuration: it picks up data from your Heroku Scheduler jobs as soon as it's installed. Learn more about Heroku Scheduler Monitor in the Heroku Elements Marketplace.

Next steps

Your job now runs weekly, monthly, or every few hours, on a daily or hourly frequency with a check that exits when it isn't due. One more thing before it goes to production: in very rare instances, Heroku Scheduler runs a job twice, and both runs pass the check. Make the job idempotent, so a second run changes nothing, for example by recording which week's digest went out and skipping it when it's already there. You'll find that practice and others in our Heroku Scheduler best practices.

Originally published:

  • Heroku Scheduler
  • Background jobs

Get more out of Heroku Scheduler

Install the add-on and start seeing data the moment Heroku Scheduler runs your next scheduled job.

Install from ElementsExplore Pricing