cron

Encore Cron Jobs

Instructions

A CronJob declaration in Encore.ts ties a schedule to an existing api(...) endpoint. The endpoint runs at the chosen cadence. Declare the CronJob at package level — not inside a function. The target endpoint must take no request parameters, as in the example below.

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

Specify exactly one of every or schedule per CronJob declaration.

Common cron expressions

Important behaviour

• Cron jobs do not execute when running locally with encore run. Only deployed environments fire crons.
• Because crons fire only in deployed environments, test the endpoint by calling it directly before deploying. For destructive jobs, consider a dry run mode or batch limits.
• The cron endpoint should be expose: false so it can't be triggered externally. This blocks public access only: other services in the app can still call it, so keep it safe under unexpected or repeated internal calls and rely on its own checks rather than on who the caller is.
• 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.