Docs › Vercel Cron Jobs with RunVouch

Vercel Cron Jobs with RunVouch

A cron entry in vercel.json hits a route on a schedule and logs the status. A route that returns 200 after an early return is a success; a function that hits its duration limit is a log line.

How it runs on Vercel Cron Jobs

Inside the route handler (Next.js route handler or serverless function), with two fetch() calls. Cron jobs run against the production deployment only.

Store the key

Project Settings, Environment Variables: RUNVOUCH_KEY, production scope. Keep CRON_SECRET as Vercel documents it so only Vercel can call the route.

Report the run (two HTTP calls)

// app/api/cron/report/route.ts
export async function GET(req: Request) {
  if (req.headers.get("authorization") !== `Bearer ${process.env.CRON_SECRET}`) return new Response("no", {status: 401});
  const h = {"X-API-Key": process.env.RUNVOUCH_KEY!, "content-type": "application/json"};
  const {run_id} = await (await fetch("https://api.runvouch.com/v1/runs/start", {method: "POST", headers: h,
    body: JSON.stringify({agent: "nightly-report", source: "vercel"})})).json();
  const rows = await buildReport();
  await fetch("https://api.runvouch.com/v1/runs/end", {method: "POST", headers: h,
    body: JSON.stringify({run_id, status: "ok", evidence: {rows: rows > 0}})});
  return Response.json({rows});
}
// vercel.json: {"crons": [{"path": "/api/cron/report", "schedule": "0 2 * * *"}]}

The start call returns run_id; the end call takes status (ok or fail), optional cost and tokens, and evidence as a JSON object of booleans. Full reference on the API page.

Register the cadence and caps

rv agent nightly-report --cadence 24h --grace 30m --max-runtime 1h --evidence --cap-run-cost 2

Register the agent once, from anywhere with the key. Cadence is what turns a schedule that stopped into an alert; --evidence makes a run without evidence a failure; the caps pause the agent when it overspends.

What goes silent on Vercel Cron Jobs

• Cron jobs only run on production; a preview deployment that looks fine never runs them. MISSED on the production agent is what tells you the schedule is not live.
• The Hobby plan runs crons once a day at most and may run them within the hour, not at the minute; set grace accordingly.
• Function duration limits end a run without a 5xx you will act on; STALLED covers a start without an end.

What RunVouch detects

Need a key? Get a free key · Stuck? contact