encore-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.

import { CronJob } from "encore.dev/cron";
import { api } from "encore.dev/api";
 
// 1. The endpoint to call (typically internal: expose: false)

Schedule Formats

Common cron expressions

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.