Background jobs

Long-running work, retries, and durable workflows. The Convex action pattern for jobs that can’t fit in a request.

Some work doesn’t fit in a request: sending 10,000 emails, processing a video, periodic data sync. For these, use Convex actions with a job table and the scheduling primitives.

The pattern

1. A job record lives in the schema

   jobs table with status (queued, running, completed, failed), payload, attempts.

2. A mutation enqueues

   Inserts a row in jobs with status queued, then schedules an action.

3. A scheduled action processes

   Picks up queued jobs, runs them, updates status. Retries on failure with exponential backoff.

4. Clients observe via reactive query

   useQuery(api.jobs.byUser) shows live status to the user.

Example: bulk email send

convex/jobs.ts

import { mutation, action } from "./_generated/server";
import { v } from "convex/values";
import { api } from "./_generated/api";

export const enqueueBulkEmail = mutation({
  args: { recipients: v.array(v.string()), subject: v.string(), html: v.string() },
  handler: async (ctx, args) => {
    const jobId = await ctx.db.insert("jobs", {
      type: "bulk_email",
      payload: args,
      status: "queued",
      attempts: 0,
    });
    await ctx.scheduler.runAfter(0, api.jobs.processEmailJob, { jobId });
    return jobId;
  },
});

export const processEmailJob = action({
  args: { jobId: v.id("jobs") },
  handler: async (ctx, { jobId }) => {
    const job = await ctx.runQuery(api.jobs.get, { id: jobId });
    if (!job || job.status !== "queued") return;
    await ctx.runMutation(api.jobs.markRunning, { id: jobId });

    try {
      for (const recipient of job.payload.recipients) {
        await fetch("https://api.resend.com/emails", { /* … */ });
      }
      await ctx.runMutation(api.jobs.markCompleted, { id: jobId });
    } catch (err) {
      const next = job.attempts + 1;
      if (next >= 3) {
        await ctx.runMutation(api.jobs.markFailed, { id: jobId, error: String(err) });
      } else {
        await ctx.runMutation(api.jobs.markRetry, { id: jobId, attempts: next });
        await ctx.scheduler.runAfter(60_000 * next, api.jobs.processEmailJob, { jobId });
      }
    }
  },
});

Limits

• Action runtime cap: 10 minutes per invocation
• For longer work, split into chunks and reschedule each chunk

Patterns to consider

Inngest integration

For complex multi-step workflows with steps, retries, and backoff built in.

Trigger.dev integration

Job queue with a polished dashboard.

Scheduled functions

For recurring (cron-like) jobs.

Webhooks pattern

For event-driven jobs.

Related

Convex actions

The function type background jobs use.

Scheduled functions

Cron + delayed scheduling.

Email campaigns recipe

Worked example.