Convex cron jobs and scheduling

Convex cron jobs and scheduling

Recurring work lives in convex/crons.ts. One off work is scheduled from inside a function with ctx.scheduler. Both must target internal.* functions, never api.*.

When to reach for this

• Something needs to run every N minutes or at a fixed time of day
• A mutation needs to kick off follow up work after it commits
• A job touches more rows than one mutation should handle
• A cron shows in the dashboard but never runs, or runs at the wrong hour
• A pending job needs to be cancelled, debounced, or inspected

Deeper material lives in two reference files:

• references/scheduling-patterns.md: open when you need retry with backoff, cancelling a job, reading _scheduled_functions, debouncing, or local time zones.
• references/cron-recipes.md: open for short copyable jobs: daily digest email, session expiry, stats rollup, external API sync.

crons.ts skeleton

One file, one default export. crons.interval for "every N", crons.cron for calendar times. crons.daily, crons.hourly, and crons.weekly are deprecated helpers. Do not use them.

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";

const crons = cronJobs();

// Every hour
crons.interval(
  "expire sessions",
  { hours: 1 },
  internal.sessions.expireBatch,
  {},
);

// Every day at 09:00 UTC. Cron expressions are always UTC.
crons.cron("daily digest", "0 9 * * *", internal.digest.send, {});

export default crons;