Encore Cron Jobs

Instructions

CronJob

api(...)

CronJob

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";

// 1. The endpoint to call (typically internal: expose: false)
export const aggregateDailyOrders = api(
  { expose: false },
  async (): Promise<void> => {
    // Aggregation logic
  }
);

// 2. Package-level cron declaration
const _ = new CronJob("aggregate-daily-orders", {
  title: "Aggregate orders for the previous day",
  schedule: "0 2 * * *",  // 02:00 UTC every day
  endpoint: aggregateDailyOrders,
});

Schedule Formats

every

"1h"

"30m"

"6h"

"7h"

schedule

"0 9 * * 1"

Common cron expressions

"0 * * * *"

"0 2 * * *"

"0 0 * * 0"

"0 4 15 * *"

Important behaviour

• Cron jobs do not execute when running locally with

  encore run

  . Only deployed environments fire crons.
• The cron endpoint should be

  expose: false

  so it can't be triggered externally — only the cron scheduler should call it.
• All times in

  schedule

  are UTC. Convert from local time when designing the schedule.
• The endpoint must already exist at module load — declare it before the

  CronJob

  .

Guidelines

• Use

  every

  for "run on a regular interval" (must divide 24h).
• Use

  schedule

  for specific times of day or days of week.
• Keep endpoint logic idempotent: a cron may fire late or be retried in a redeploy window.
• For event-driven background work (not time-driven), use the

  encore-pubsub

  skill instead.