convex-cron-jobs

Name: convex-cron-jobs - Agent Skill
Rating: 3.4 (190 reviews)
Author: waynesutton

190

Scheduled function patterns for background tasks including interval scheduling, cron expressions, job monitoring, retry strategies, and best practices for long-running tasks

Download Folder View on GitHub

CLI Install

Recommended

Use the skills CLI to install this skill with one command. Auto-detects all installed AI assistants.

Method 1 - skills CLI

npx skills i waynesutton/convexskills/skills/convex-cron-jobs

Method 2 - openskills (supports sync & update)

npx openskills install waynesutton/convexskills

Auto-detects Claude Code, Cursor, Codex CLI, Gemini CLI, and more. One install, works everywhere.

Installation Path

Download and extract to one of the following locations:

~/.claude/skills/convex-cron-jobs/

SKILL.md

agents

assets

Skill Instructions

Back

Run with Cloud Agent

No setup needed. Let our cloud agents run this skill for you.

Select Provider

Select Model

Claude Sonnet 4.5

$0.20/task

Best for coding tasks

Environment setup included

Convex Cron Jobs

Schedule recurring functions for background tasks, cleanup jobs, data syncing, and automated workflows in Convex applications.

Documentation Sources

Before implementing, do not assume; fetch the latest documentation:

Primary: https://docs.convex.dev/scheduling/cron-jobs
Scheduling Overview: https://docs.convex.dev/scheduling
Scheduled Functions: https://docs.convex.dev/scheduling/scheduled-functions
For broader context: https://docs.convex.dev/llms.txt

Instructions

Cron Jobs Overview

Convex cron jobs allow you to schedule functions to run at regular intervals or specific times. Key features:

Run functions on a fixed schedule
Support for interval-based and cron expression scheduling
Automatic retries on failure
Monitoring via the Convex dashboard

Basic Cron Setup

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
// Run every hour
crons.interval(
  "cleanup expired sessions",
  { hours: 1 },
  internal.tasks.cleanupExpiredSessions,
  {}
);

Interval-Based Scheduling

Use crons.interval for simple recurring tasks:

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
// Every 5 minutes
crons.interval(
  "sync external data",
  { minutes: 5 },
  internal.sync.fetchExternalData,
  {}

Cron Expression Scheduling

Use crons.cron for precise scheduling with cron expressions:

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
// Every day at 9 AM UTC
crons.cron(
  "morning notifications",
  "0 9 * * *",
  internal.notifications.sendMorningDigest,

Cron Expression Reference

┌───────────── minute (0-59)
│ ┌───────────── hour (0-23)
│ │ ┌───────────── day of month (1-31)
│ │ │ ┌───────────── month (1-12)
│ │ │ │ ┌───────────── day of week (0-6, Sunday=0)
│ │ │ │ │
* * * * *

Common patterns:

* * * * * - Every minute
0 * * * * - Every hour
0 0 * * * - Every day at midnight
0 0 * * 0 - Every Sunday at midnight
0 0 1 * * - First day of every month
*/5 * * * * - Every 5 minutes
0 9-17 * * 1-5 - Every hour from 9 AM to 5 PM, Monday through Friday

Internal Functions for Crons

Cron jobs should call internal functions for security:

// convex/tasks.ts
import { internalMutation, internalQuery } from "./_generated/server";
import { v } from "convex/values";
 
// Cleanup expired sessions
export const cleanupExpiredSessions = internalMutation({
  args: {},

Cron Jobs with Arguments

Pass static arguments to cron jobs:

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
// Different cleanup intervals for different types
crons.interval(
  "cleanup temp files",
  { hours: 1 },
  internal.cleanup.cleanupByType,
  { fileType: "temp"

// convex/cleanup.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
 
export const cleanupByType = internalMutation({
  args: {
    fileType: v.string(),
    maxAge: v.number(),
  },
  returns: v.

Monitoring and Logging

Add logging to track cron job execution:

// convex/tasks.ts
import { internalMutation } from "./_generated/server";
import { v } from "convex/values";
 
export const cleanupWithLogging = internalMutation({

Batching for Large Datasets

Handle large datasets in batches to avoid timeouts:

// convex/tasks.ts
import { internalMutation } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
 
const BATCH_SIZE = 100;
 
export const processBatch

External API Calls in Crons

Use actions for external API calls:

// convex/sync.ts
"use node";
 
import { internalAction } from "./_generated/server";
import { internal } from "./_generated/api";
import { v } from "convex/values";
 
export const syncExternalData

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
crons.interval(
  "sync external data",
  { minutes: 15 },
  internal.sync.syncExternalData,
  {}
);
 
export default crons;

Examples

Schema for Cron Job Logging

// convex/schema.ts
import { defineSchema, defineTable } from "convex/server";
import { v } from "convex/values";
 
export default defineSchema({
  cronLogs: defineTable({
    jobName: v.

Complete Cron Configuration Example

// convex/crons.ts
import { cronJobs } from "convex/server";
import { internal } from "./_generated/api";
 
const crons = cronJobs();
 
// Cleanup jobs
crons.interval(
  "cleanup expired sessions",
  { hours: 1 },

Best Practices

Never run npx convex deploy unless explicitly instructed
Never run any git commands unless explicitly instructed
Only use crons.interval or crons.cron methods, not deprecated helpers
Always call internal functions from cron jobs for security
Import internal from _generated/api even for functions in the same file
Add logging and monitoring for production cron jobs
Use batching for operations that process large datasets
Handle errors gracefully to prevent job failures
Use meaningful job names for dashboard visibility
Consider timezone when using cron expressions (Convex uses UTC)

Common Pitfalls

Using public functions - Cron jobs should call internal functions only
Long-running mutations - Break large operations into batches
Missing error handling - Unhandled errors will fail the entire job
Forgetting timezone - All cron expressions use UTC
Using deprecated helpers - Avoid crons.hourly, crons.daily, etc.
Not logging execution - Makes debugging production issues difficult

References

Convex Documentation: https://docs.convex.dev/
Convex LLMs.txt: https://docs.convex.dev/llms.txt
Cron Jobs: https://docs.convex.dev/scheduling/cron-jobs
Scheduling Overview: https://docs.convex.dev/scheduling
Scheduled Functions: https://docs.convex.dev/scheduling/scheduled-functions

// Run every day at midnight UTC

internal.reports.generateDailyReport,

export default crons;

"cleanup temp files",

internal.files.cleanupTempFiles,

// Every 30 seconds (minimum interval)

internal.monitoring.healthCheck,

export default crons;

// Every Monday at 8 AM UTC

internal.reports.generateWeeklySummary,

// First day of every month at midnight

internal.billing.processMonthlyBilling,

internal.sync.syncData,

export default crons;

returns: v.number(),

handler: async (ctx) => {

const oneHourAgo = Date.now() - 60 * 60 * 1000;

const expiredSessions = await ctx.db

.withIndex("by_lastActive")

.filter((q) => q.lt(q.field("lastActive"), oneHourAgo))

for (const session of expiredSessions) {

await ctx.db.delete(session._id);

return expiredSessions.length;

// Process pending tasks

export const processPendingTasks = internalMutation({

handler: async (ctx) => {

const pendingTasks = await ctx.db

.withIndex("by_status", (q) => q.eq("status", "pending"))

for (const task of pendingTasks) {

await ctx.db.patch(task._id, {

status: "processing",

startedAt: Date.now(),

// Schedule the actual processing

await ctx.scheduler.runAfter(0, internal.tasks.processTask, {

"cleanup cache files",

internal.cleanup.cleanupByType,

{ fileType: "cache", maxAge: 86400000 }

export default crons;

handler: async (ctx, args) => {

const cutoff = Date.now() - args.maxAge;

const oldFiles = await ctx.db

.withIndex("by_type_and_created", (q) =>

q.eq("type", args.fileType).lt("createdAt", cutoff)

for (const file of oldFiles) {

await ctx.storage.delete(file.storageId);

await ctx.db.delete(file._id);

return oldFiles.length;

handler: async (ctx) => {

const startTime = Date.now();

let processedCount = 0;

const expiredItems = await ctx.db

.withIndex("by_expiresAt")

.filter((q) => q.lt(q.field("expiresAt"), Date.now()))

for (const item of expiredItems) {

await ctx.db.delete(item._id);

console.error(`Failed to delete item ${item._id}:`, error);

// Log job completion

await ctx.db.insert("cronLogs", {

endTime: Date.now(),

duration: Date.now() - startTime,

status: errorCount === 0 ? "success" : "partial",

await ctx.db.insert("cronLogs", {

endTime: Date.now(),

duration: Date.now() - startTime,

error: String(error),

cursor: v.optional(v.string()),

handler: async (ctx, args) => {

const result = await ctx.db

.withIndex("by_status", (q) => q.eq("status", "pending"))

.paginate({ numItems: BATCH_SIZE, cursor: args.cursor ?? null });

for (const item of result.page) {

await ctx.db.patch(item._id, {

status: "processed",

processedAt: Date.now(),

// Schedule next batch if there are more items

if (!result.isDone) {

await ctx.scheduler.runAfter(0, internal.tasks.processBatch, {

cursor: result.continueCursor,

handler: async (ctx) => {

// Fetch from external API

const response = await fetch("https://api.example.com/data", {

Authorization: `Bearer ${process.env.API_KEY}`,

throw new Error(`API request failed: ${response.status}`);

const data = await response.json();

// Store the data using a mutation

await ctx.runMutation(internal.sync.storeExternalData, {

syncedAt: Date.now(),

export const storeExternalData = internalMutation({

syncedAt: v.number(),

handler: async (ctx, args) => {

await ctx.db.insert("externalData", {

syncedAt: args.syncedAt,

startTime: v.number(),

endTime: v.number(),

duration: v.number(),

processedCount: v.number(),

errorCount: v.number(),

v.literal("success"),

v.literal("partial"),

error: v.optional(v.string()),

.index("by_job", ["jobName"])

.index("by_status", ["status"])

.index("by_startTime", ["startTime"]),

sessions: defineTable({

userId: v.id("users"),

lastActive: v.number(),

expiresAt: v.number(),

.index("by_user", ["userId"])

.index("by_lastActive", ["lastActive"])

.index("by_expiresAt", ["expiresAt"]),

tasks: defineTable({

v.literal("pending"),

v.literal("processing"),

v.literal("completed"),

createdAt: v.number(),

startedAt: v.optional(v.number()),

completedAt: v.optional(v.number()),

.index("by_status", ["status"])

.index("by_type_and_status", ["type", "status"]),

internal.cleanup.expiredSessions,

internal.cleanup.oldLogs,

internal.sync.userData,

internal.reports.dailyAnalytics,

internal.reports.weeklySummary,

"service health check",

internal.monitoring.healthCheck,

export default crons;