Vercel Schedules guidance — run a private function, route, or Vercel Queues topic on a cron cadence or once at a set time. Covers static schedules in vercel.json, dynamic per-user schedules with @vercel/schedules, handleSchedule, the vercel schedules CLI, environments, jitter, and migrating from Cron Jobs. Use when adding scheduled or recurring work, one-time reminders, or replacing `crons`.
90%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
Passed
No findings from the security scan
You are an expert in Vercel Schedules, which runs code on a recurring cron cadence or once at a specific time.
| Static | Dynamic | |
|---|---|---|
| Defined in | vercel.json schedules (or Build Output API config.json) | @vercel/schedules SDK or vercel schedules CLI |
| Takes effect | When the deployment becomes current for its environment/branch | Immediately |
| Targets | function, path, or topic | topic only |
| One-time runs | No | Yes |
| Payload / namespace | No / always default | Optional JSON (≤ 8 KB) / any namespace |
| Update or delete | Edit config and redeploy | SDK or CLI |
Use static for jobs that belong to the app (nightly cleanup, hourly sync). Use dynamic for jobs the app creates for users (a reminder per customer, a report at 09:00 in each tenant's timezone).
| Target | Use when | Retries |
|---|---|---|
function (default) | Any new static schedule. The handler has no public URL, and only Vercel's scheduler can invoke it, so there's no secret to manage. | No |
topic | Failed runs must be retried, you need a payload, or the schedule is dynamic. | Yes, via Queues |
path | Only when migrating an existing Cron Job and you don't want to change any code. | No |
Prefer function over path. A path target exposes your handler to the public internet, and its only protection is a static CRON_SECRET that you have to store, check on every request, and rotate. A function target has neither problem. Don't pick path for new schedules, and don't pick it because a route "already exists". Wrapping the route in handleSchedule and adding the trigger is a small change.
If a failed run must be retried, target a queue topic.
npm i @vercel/schedules// api/cleanup.ts
import { handleSchedule } from '@vercel/schedules';
export const POST = handleSchedule(async (metadata) => {
console.log(`${metadata.name} run ${metadata.executionId} for ${metadata.scheduledAt.toISOString()}`);
await deleteExpiredRecords();
});{
"$schema": "https://openapi.vercel.sh/vercel.json",
"functions": {
"api/cleanup.ts": {
"experimentalTriggers": [{ "type": "schedule/v1beta" }]
}
},
"schedules": {
"cleanup": {
"schedule": "0 * * * *",
"function": "api/cleanup"
}
}
}Test locally, then deploy:
vercel dev # starts a local scheduler
vercel schedules invoke cleanup --local # second terminal: run it now
vercel deploy --prod
vercel schedules invoke cleanup # run once in productionfunction is the build output path relative to .vercel/output/functions, without .func — not the source filename. api/jobs/report.ts → api/jobs/report. When unsure, run vercel build and look in .vercel/output/functions.{ "type": "schedule/v1beta" }, and it must be its only trigger. It can't also have a queue/v2beta trigger.schedule/v1beta function. It is private by design.service plus function relative to .vercel/output/services/<name>/functions. vercel dev can't run these yet (DEV_SCHEDULE_SERVICE_FUNCTION_UNSUPPORTED).function, path, or topic.vercel.json schedules with the same name fail with SCHEDULE_NAME_CONFLICT.| Property | Notes |
|---|---|
schedule | Required. Five-field cron, evaluated in timezone. |
timezone | IANA name such as America/New_York. Defaults to UTC. Follows DST. |
jitter | Minutes, 1–15. Defaults to 1 on Pro/Enterprise. Hobby is always 15. |
function / service | Private function target (see rules above). |
path / requestMethod | Public route target, for code-free Cron Jobs migration only. Path must start with /. Method defaults to POST. |
topic | Vercel Queues topic. Letters, digits, _, -. |
The object key is the schedule name: 1–256 chars of ASCII letters, digits, ., _, -, starting with a letter or digit. Keep names stable. Renaming deletes the schedule and creates a new one with fresh state and history. A project can have up to 100 static schedules.
Cron syntax: digits, *, ,, -, / only. No MON/JAN names, and don't set both day-of-month and day-of-week.
Use a path target only to move an existing Cron Job over without touching its route code. For anything else, use a function target. The route stays publicly reachable, so it must check CRON_SECRET on every request:
{
"schedules": {
"daily-report": { "schedule": "0 9 * * *", "path": "/api/daily-report", "requestMethod": "GET" }
}
}// api/daily-report.ts
export async function GET(request: Request) {
const cronSecret = process.env.CRON_SECRET;
if (!cronSecret || request.headers.get('authorization') !== `Bearer ${cronSecret}`) {
return new Response('Unauthorized', { status: 401 });
}
await sendReport();
return new Response(null, { status: 200 });
}CRON_SECRET should be a random string of at least 16 characters. handleSchedule also works on path routes (GET or POST), but it does not check CRON_SECRET, so keep the check. Function targets never receive authorization or Cron Job headers, so don't require them there.
The consumer is a normal Vercel Queues consumer (⤳ skill: queues):
// api/reminders.ts
import { handleCallback } from '@vercel/queue';
interface ScheduleQueueMessage {
scheduleId: string;
executionId: string;
name: string;
namespace: string;
scheduledAt: string; // ISO 8601, excludes jitter
source: 'static' | 'dynamic';
payload?: { userId: string };
}
export const POST = handleCallback(async (message: ScheduleQueueMessage) => {
await sendReminder(message.payload!.userId, message.executionId);
});{
"functions": {
"api/reminders.ts": {
"experimentalTriggers": [{ "type": "queue/v2beta", "topic": "reminders" }]
}
}
}Create schedules at runtime from app code. The SDK authenticates with the deployment's OIDC token and acts on that deployment's environment or branch:
import { Schedules, SchedulesApiError } from '@vercel/schedules';
// Recurring, per tenant
await Schedules.create({
namespace: `tenant-${tenantId}`,
name: 'daily-digest',
target: { topic: 'digests' },
expression: { type: 'cron', cron: '0 9 * * *' },
timezone: tenant.timezone,
payload: { tenantId },
});
// One-time, local date and time in `timezone` (no Z, no offset)
await Schedules.create({
name: `reminder-${reminderId}`,
target: { topic: 'reminders' },
expression: { type: 'single', at: '2026-11-01T09:00' },
timezone: 'America/New_York',
payload: { userId },
});
// Idempotent create
try {
await Schedules.create({ /* ... */ });
} catch (error) {
if (!(error instanceof SchedulesApiError && error.code === 'schedule_already_exists')) throw error;
}Other methods: get, list (paginate with cursor), update (dynamic only, can't switch cron ↔ one-time), enable (optionally until), disable, invoke (run now), delete (dynamic only). Use one namespace per tenant so a tenant's schedules can be listed and cleaned up together.
executionId is the same for every delivery of an occurrence. Record it and skip repeats.scheduledAt to now and return early.500 in execution history, and that's it.Vercel keeps separate schedules for production, each custom environment, each Preview branch, and CLI deployments per user.
vercel schedules enable <name> --git-branch <branch> --for 2h.--environment, --git-branch, --user, or --local to pick another set.| Hobby | Pro / Enterprise | |
|---|---|---|
| Jitter window | Always 15 min | 1–15 min, default 1 |
| Most frequent cron | Every 15 min | Every minute |
| Schedules per team | 1,000 | 10,000 / 100,000 |
The shortest interval between runs must be at least the jitter window (jitter_exceeds_cadence). On Hobby, omit jitter or set it to 15. Downgrading to Hobby deletes schedules that run more often than every 15 minutes or set jitter below 15.
Replace each crons entry with a named schedules entry. Keep path and schedule, and add "requestMethod": "GET", because Cron Jobs send GET and path schedules default to POST. Remove crons in the same change, or the route runs twice. Existing CRON_SECRET checks and vercel-cron/1.0 headers keep working. Leave timezone unset to keep UTC run times. This is the only case where a path target makes sense. If you can change code, go straight to a private function target instead: wrap the handler in handleSchedule, add the schedule/v1beta trigger, replace path/requestMethod with function, drop the CRON_SECRET check, and keep the same name so the schedule keeps its state and history.
node-cron, setInterval, or any in-process scheduler. Functions aren't long-lived, so they never fire reliably.path target for a new schedule. It exposes the handler publicly and depends on a static CRON_SECRET. Use a function target.path target with no CRON_SECRET check. Anyone on the internet can trigger it.vercel schedules list
vercel schedules inspect cleanup --json
vercel schedules executions list cleanup --since 7d
vercel schedules disable cleanup
vercel schedules enable cleanup --for 2h
vercel schedules invoke cleanup
vercel schedules create send-reminder --at 2026-11-01T09:00 --timezone America/New_York --topic remindersIn the dashboard, open the project and select Schedules to see next run times, execution history, and Run Schedule.
Common SDK error codes: invalid_cron_expression, invalid_jitter, jitter_exceeds_cadence, single_at_in_past, payload_too_large, static_schedule (tried to update/delete a static one), rate_limited (wait retryAfter seconds).
⤳ skill: queues for queue consumers, retries, and idempotency⤳ skill: workflow for multi-step durable logic triggered by a schedule⤳ skill: vercel-functions for function runtime and duration limitsvercel/vercel-plugin
808a6c9
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.