go-cron

Encore Go Cron Jobs

Instructions

A cron.NewJob declaration in Encore Go ties a schedule to an existing //encore:api endpoint. The endpoint runs at the chosen cadence. Declare the job as a package-level variable — not inside a function.

package cleanup

import (
    "context"
    "encore.dev/cron"
)

// 1. The endpoint to call (private by default: //encore:api private)
//encore:api private
func CleanupExpiredSessions(ctx context.Context) error {
    // Cleanup logic
    return nil
}

// 2. Package-level cron declaration
var _ = cron.NewJob("cleanup-sessions", cron.JobConfig{
    Title:    "Clean up expired sessions",
    Schedule: "0 * * * *", // Every hour
    Endpoint: CleanupExpiredSessions,
})

Schedule Formats

Set exactly one of Every or Schedule in the job config, never both.

Common cron expressions

Important behaviour

• Cron jobs do not execute when running locally with encore run. Only deployed environments fire crons. To check the job logic before deploying, call the endpoint function directly while developing, and verify it in a test environment before production.
• Declare the cron endpoint private by default so it can't be triggered externally. Other services in the same app can still call it, so keep validation and safety limits inside the handler.
• All times in Schedule are UTC. Convert from local time when designing the schedule.
• Cron endpoints take no request payload: they accept only a context and return an error, like the example above.
• The endpoint must be an //encore:api function referenced from a package-level cron.NewJob declaration; declaration order within the package does not matter.

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: invocations may fire late, overlap or repeat, for example around redeploys.
• For event-driven background work (not time-driven), use the encore-go-pubsub skill instead.