Run a 3-Minute Background Job on Vercel Hobby with cron-job.org

What limits are you working around?

Three limits collide here. Vercel's built-in cron on Hobby only accepts schedules that run once per day; an hourly expression fails the deployment. External schedulers fix the frequency, but cron-job.org waits at most 30 seconds for a response. And the function itself has a maximum duration.

The pattern: respond 202, keep working with waitUntil

The route authenticates the caller, creates a run record, starts the job inside waitUntil(), and returns 202 Accepted within a second or two. cron-job.org sees a fast 2xx and logs a success. Vercel keeps the function alive until the promise settles or maxDuration is reached.

On Next.js 15.1 and later, Vercel recommends the built-in after() from next/server for the same job. This site is on Next.js 14, so it uses waitUntil().

// app/api/cron/job/route.js
import { NextResponse } from "next/server";
import { waitUntil } from "@vercel/functions";
import { timingSafeEqual } from "node:crypto";

export const runtime = "nodejs";
export const dynamic = "force-dynamic";
export const maxDuration = 300; // Hobby max, needs Fluid Compute

function authorized(req) {
  const secret = process.env.CRON_SECRET || "";
  const header = req.headers.get("authorization") || "";
  const a = Buffer.from(header.replace(/^Bearer /, ""));
  const b = Buffer.from(secret);
  return secret && a.length === b.length && timingSafeEqual(a, b);
}

export async function GET(req) {
  if (!authorized(req)) return NextResponse.json({ ok: false }, { status: 401 });
  const run = await Run.create({ status: "running", stage: "start" });
  waitUntil(doTheWork(run)); // keeps running after the response
  return NextResponse.json({ ok: true, runId: String(run._id) }, { status: 202 });
}

Turn on Fluid Compute first

The 300-second Hobby limit applies to functions running on Fluid Compute. Without it, Hobby functions are capped at 60 seconds, and setting maxDuration = 300 failed my deployment with: Serverless Functions must have a maxDuration between 1 and 60 for plan hobby.

Enable Fluid Compute in the project's Settings, under Functions, or commit it in vercel.json so it can't be switched off by accident.

{
  "$schema": "https://openapi.vercel.sh/vercel.json",
  "fluid": true
}

Record every run so failures are visible

Background work fails quietly: cron-job.org already got its 202. I store one small document per run with the stage it reached (scrape, generate, save, revalidate, done), the error message and the duration, and expire those documents after 30 days with a TTL index.

A ?status=1 query on the same route returns the last ten runs. A run still marked running after maxDuration plus a margin was killed by the platform, and the stage tells you where.

const RunSchema = new Schema(
  {
    status: { type: String, enum: ["running", "success", "skipped", "error"], default: "running" },
    stage: String,
    error: String,
    ms: Number,
  },
  { timestamps: true }
);
// delete runs after 30 days
RunSchema.index({ createdAt: 1 }, { expireAfterSeconds: 60 * 60 * 24 * 30 });

async function doTheWork(run) {
  const stage = (s, extra = {}) => Run.updateOne({ _id: run._id }, { stage: s, ...extra });
  const started = Date.now();
  try {
    await stage("fetch");
    // ...
    await stage("done", { status: "success", ms: Date.now() - started });
  } catch (err) {
    await Run.updateOne({ _id: run._id }, { status: "error", error: err.message, ms: Date.now() - started });
  }
}

Stop slow calls before Vercel stops you

If an API call is still running when the function hits maxDuration, the whole invocation is cancelled and your catch block never runs. Give long calls their own deadline that ends before the platform's, using whatever time is left.

AbortSignal.timeout() works with fetch in Node.js 18 and later. @vercel/functions also exposes getDeadline(), which returns the invocation's shared deadline if you'd rather compute the budget from that.

const budgetMs = (maxDuration - 45) * 1000 - (Date.now() - started);
const res = await fetch(apiUrl, {
  method: "POST",
  body: JSON.stringify(payload),
  signal: AbortSignal.timeout(Math.max(20_000, budgetMs)),
});

Prevent double runs

Schedulers retry, people click "run now", and a job set to every 15 minutes by mistake can flood your database. Two cheap checks cover it: skip if a run started within the last maxDuration seconds is still marked running, and skip if the last successful result is newer than your minimum interval. Return 200 with skipped: true, so the scheduler doesn't log an intentional skip as a failure.

const running = await Run.findOne({
  status: "running",
  createdAt: { $gt: new Date(Date.now() - (maxDuration + 30) * 1000) },
});
if (running) return NextResponse.json({ ok: true, skipped: true, reason: "in progress" });

How to set up the job on cron-job.org

cron-job.org is free and takes a couple of minutes to configure. These are the settings this site uses for a job that runs every two hours.

• URL: the full production URL of the route, for example https://example.com/api/cron/job, exactly as it resolves with no redirect.
• Schedule: every 2 hours, or the crontab expression 0 */2 * * *.
• Advanced, Headers: add Authorization with the value Bearer <your CRON_SECRET>.
• Method: GET is fine if your route exports a GET handler; this site exports the same handler for GET and POST.
• Notifications: turn on failure emails. Because the route answers 202 quickly, a failure here means auth, routing or a cold-start problem, not the job itself.

What one run looks like, second by second

Here is the time budget this site's blog job is designed around, which helps when deciding where to put your own deadlines. Actual times vary from run to run, mostly with how long the model takes.

Gotchas I ran into

• Point the cron job at the final URL. A redirect, for example apex domain to www, can drop the Authorization header, and the job starts failing with 401.
• On Next.js 14, my calls to revalidatePath() from inside the background work didn't refresh the pages, so the job calls its own route with a ?revalidate= flag once the post is saved, and that request revalidates.
• Compare secrets with crypto.timingSafeEqual and check lengths first, because it throws on buffers of different length.
• Keep the cron secret in an environment variable and send it as a header. A secret in the query string ends up in logs.

Frequently asked questions

Sources & further reading

• Vercel docs: Functions limits
• Vercel docs: Cron jobs usage and pricing
• Vercel docs: @vercel/functions (waitUntil, getDeadline)
• Vercel docs: Fluid compute
• cron-job.org FAQ