Convex Scheduling — Delayed Functions & Cron Jobs

Schedule functions for future execution and define recurring cron jobs — durable, no external infrastructure needed.

Scheduling API

runAfter — delay in milliseconds

import { internal } from "./_generated/api";

// Schedule deletion in 5 seconds const scheduledId = await ctx.scheduler.runAfter(5000, internal.messages.destruct, { messageId: id, });

runAt — specific timestamp (ms since epoch)

await ctx.scheduler.runAt(args.remindAt, internal.reminders.send, { reminderId });

runAfter(0) — immediate, conditional on mutation success

Like setTimeout(fn, 0) . Use to trigger an action from a mutation — only runs if mutation succeeds.

export const createUser = mutation({ handler: async (ctx, args) => { const userId = await ctx.db.insert("users", args); // Only runs if insert succeeds (atomic with mutation) await ctx.scheduler.runAfter(0, internal.users.generateAIProfile, { userId }); return userId; }, });

cancel

await ctx.scheduler.cancel(scheduledFunctionId);

State when canceled Behavior

Not started Won't run

Already started Continues, but its scheduled children won't run

Mutation vs Action Scheduling

Scheduling from Atomicity On failure

Mutation Atomic with the rest of the mutation Nothing scheduled if mutation fails

Action NOT atomic Scheduled functions still execute even if action throws

Rule: Prefer scheduling from mutations for guaranteed consistency. If scheduling from an action, be aware that scheduled children survive parent failure.

Tracking Status

runAfter /runAt return a Id<"_scheduled_functions"> . Query the system table:

// Get all scheduled functions const all = await ctx.db.system.query("_scheduled_functions").collect();

// Get specific one const fn = await ctx.db.system.get(scheduledId); // fn.state.kind: "pending" | "inProgress" | "success" | "failed" | "canceled" // fn.scheduledTime, fn.completedTime, fn.name, fn.args

Results available for 7 days after completion.

Cancellable Pattern

Store the scheduled ID to allow cancellation later:

export const createReminder = mutation({ handler: async (ctx, args) => { const scheduledId = await ctx.scheduler.runAfter( args.delayMs, internal.reminders.send, { message: args.message } ); return await ctx.db.insert("reminders", { message: args.message, scheduledFunctionId: scheduledId, status: "scheduled", }); }, });

export const cancelReminder = mutation({ args: { reminderId: v.id("reminders") }, handler: async (ctx, { reminderId }) => { const reminder = await ctx.db.get(reminderId); if (!reminder) throw new Error("Not found"); await ctx.scheduler.cancel(reminder.scheduledFunctionId); await ctx.db.patch(reminderId, { status: "canceled" }); }, });

Error Handling

Function type Execution guarantee Auto-retry

Scheduled mutation Exactly once Yes (internal errors)

Scheduled action At most once No — permanently fails on transient errors/timeout

Retry pattern for actions

export const reliableAction = internalAction({ args: { taskId: v.id("tasks") }, handler: async (ctx, args) => { try { await fetch("https://api.example.com/process"); await ctx.runMutation(internal.tasks.markComplete, { taskId: args.taskId }); } catch (error) { // Schedule retry through a mutation (atomic retry count check) await ctx.scheduler.runAfter(60000, internal.tasks.retryAction, { taskId: args.taskId, }); } }, });

export const retryAction = internalMutation({ args: { taskId: v.id("tasks") }, handler: async (ctx, { taskId }) => { const task = await ctx.db.get(taskId); if (task?.completed) return; if ((task?.retries ?? 0) >= 3) { await ctx.db.patch(taskId, { status: "failed" }); return; } await ctx.db.patch(taskId, { retries: (task?.retries ?? 0) + 1 }); await ctx.scheduler.runAfter(0, internal.tasks.reliableAction, { taskId }); }, });

Authentication

Auth is NOT propagated from the scheduling function to the scheduled function. Pass user info explicitly:

export const scheduleUserTask = mutation({ handler: async (ctx, args) => { const identity = await ctx.auth.getUserIdentity(); if (!identity) throw new Error("Not authenticated"); await ctx.scheduler.runAfter(5000, internal.tasks.process, { userId: identity.subject, // pass explicitly taskData: args.taskData, }); }, });

Cron Jobs

Define in convex/crons.ts :

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

const crons = cronJobs();

// Interval (first run on deploy) crons.interval("check queue", { seconds: 30 }, internal.queue.process); crons.interval("cleanup", { minutes: 5 }, internal.files.cleanTemp); crons.interval("sync", { hours: 2 }, internal.sync.fetchExternal);

// Hourly crons.hourly("metrics", { minuteUTC: 0 }, internal.metrics.collect);

// Daily crons.daily("digest", { hourUTC: 8, minuteUTC: 0 }, internal.emails.sendDigest);

// Weekly (dayOfWeek: "monday" | "tuesday" | ... | "sunday") crons.weekly("backup", { dayOfWeek: "sunday", hourUTC: 2, minuteUTC: 0 }, internal.backup.run);

// Monthly crons.monthly("billing", { day: 1, hourUTC: 9, minuteUTC: 0 }, internal.billing.process);

// Traditional cron syntax (UTC) — "minute hour day-of-month month day-of-week" crons.cron("weekday reminder", "0 17 * * 1-5", internal.reminders.send);

// With arguments crons.daily("report", { hourUTC: 8, minuteUTC: 0 }, internal.reports.generate, { type: "daily", });

export default crons;

Cron rules:

• At most ONE run executing at a time per cron job

• If a run takes too long, following runs may be skipped (logged in dashboard)

• Same error guarantees as scheduled functions (mutations: exactly once, actions: at most once)

Limits & Rules

Limit Value

Max scheduled per mutation/action 1000

Max total argument size 8 MB

Results retention 7 days

Auth propagation None — pass userId explicitly

Mutation scheduling Atomic (all-or-nothing)

Action scheduling Non-atomic (survives failure)

Cron concurrency At most 1 concurrent run per job

Reference Files

• Full examples: Self-destructing messages, payment reminders, background job queue, rate limiting, complete cron file → See references/examples.md