Index of every page on this site: llms.txt
All skills
vercel avatar

/vercel-schedules

@250769d official
by vercelvercel/vercel-plugin340 stars
82
Run it yourself

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`.

Use this Skill: https://skilld.dev/gh/vercel/vercel-plugin/vercel-schedules

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈104 tokens for metadata: the name and description. ≈2.9k when used: this file.

Description uses 5.2% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈413 characters, or 5.2%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

Vercel Schedules

You are an expert in Vercel Schedules, which runs code on a recurring cron cadence or once at a specific time.

Choose static or dynamic

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 (≤ 16 KB; 8 KB with --local) / 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).

Choose a target

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.

Quickstart: private function on a static schedule

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 production

Rules that break deployments

  • function 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.
  • The target function must declare { "type": "schedule/v1beta" }, and it must be its only trigger. It can't also have a queue/v2beta trigger.
  • Don't add routes or rewrites to a schedule/v1beta function. It is private by design.
  • For a function in a service, set service plus function relative to .vercel/output/services/<name>/functions. vercel dev can't run these yet (DEV_SCHEDULE_SERVICE_FUNCTION_UNSUPPORTED).
  • Set exactly one of function, path, or topic.
  • A framework's Build Output API schedules and vercel.json schedules with the same name fail with SCHEDULE_NAME_CONFLICT.

Static schedule properties

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. On Hobby, a deployment can declare up to 100 static schedules. On every plan, the CLI rejects a vercel.json with more than 500 schedules entries (Vercel CLI 65.11+; older CLIs cap it at 100).

Cron syntax: digits, *, ,, -, / only. No MON/JAN names, and don't set both day-of-month and day-of-week.

Path targets (Cron Jobs migration only)

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.

Queue targets and dynamic schedules

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.

Handlers must be idempotent

  • A run can be delivered more than once, and queue targets retry. executionId is the same for every delivery of an occurrence. Record it and skip repeats.
  • After an outage, every unexpired occurrence is delivered, so a frequent schedule can fire several times in a row. If the work only makes sense near its scheduled time, compare scheduledAt to now and return early.
  • Runs are independent. A slow run doesn't delay the next one, so runs can overlap. Guard shared resources.
  • Function and path targets are not retried. A thrown error becomes a 500 in execution history, and that's it.

Environments

Vercel keeps separate schedules for production, each custom environment, each Preview branch, and CLI deployments per user.

  • Static schedules apply when a deployment becomes current, including promotions and rollbacks.
  • New static schedules start active in production and inactive in Preview and custom environments. Enable them in the dashboard or with vercel schedules enable <name> --git-branch <branch> --for 2h.
  • Enabled/disabled state persists across later deployments.
  • The CLI defaults to production. Use --environment, --git-branch, --user, or --local to pick another set.

Jitter and plan limits

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.

Migrate from Cron Jobs

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.

Never do this on Vercel

  • node-cron, setInterval, or any in-process scheduler. Functions aren't long-lived, so they never fire reliably.
  • A path target for a new schedule. It exposes the handler publicly and depends on a static CRON_SECRET. Use a function target.
  • A path target with no CRON_SECRET check. Anyone on the internet can trigger it.
  • Renaming a schedule to "fix" it. That resets its state and history.

Manage and debug

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 reminders

In 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).

Related

  • ⤳ 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 limits
  • Schedules docs

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

No alerts10d3 checks · Risk SAFE
  • Gen Agent Trust Hub10d

    This skill provides guidance on using Vercel Schedules for recurring and one-time tasks. It covers static configuration in `vercel.json`, dynamic scheduling with the `@vercel/schedules` SDK, and security best practices like using private function targets and environment-based secrets. No security issues were detected.

  • Socket10d

    No alerts

  • Snyk10d

    Risk: LOW · No issues

Signed by skilld at 250769d. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub yesterday.

Activeupdated 2 weeks ago
Other metadata
summary
Vercel Schedules replaces Cron Jobs. Static schedules go in vercel.json under `schedules` and target a private `function` (with an `experimentalTriggers: [{ type: 'schedule/v1beta' }]` trigger; the default), a queue `topic`, or a public `path` (only to migrate Cron Jobs without code changes). Dynamic schedules come from `Schedules.create()` in `@vercel/schedules` or `vercel schedules create`, target queue topics only, and support one-time runs, payloads, and namespaces. Wrap function handlers in `handleSchedule`; make handlers idempotent with `executionId`.
metadata
{
  "priority": 6,
  "docs": [
    "https://vercel.com/docs/schedules",
    "https://vercel.com/docs/schedules/quickstart",
    "https://vercel.com/docs/schedules/handle-runs",
    "https://vercel.com/docs/schedules/configuration",
    "https://vercel.com/docs/schedules/sdk",
    "https://vercel.com/docs/cli/schedules"
  ],
  "sitemap": "https://vercel.com/sitemap.xml",
  "pathPatterns": [
    "vercel.json",
    "app/api/schedules/**",
    "src/app/api/schedules/**",
    "api/schedules/**",
    "lib/schedules.*",
    "src/lib/schedules.*",
    "lib/schedules/**",
    "src/lib/schedules/**"
  ],
  "bashPatterns": [
    "\\bnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/schedules\\b",
    "\\bpnpm\\s+(install|i|add)\\s+[^\\n]*@vercel/schedules\\b",
    "\\bbun\\s+(install|i|add)\\s+[^\\n]*@vercel/schedules\\b",
    "\\byarn\\s+add\\s+[^\\n]*@vercel/schedules\\b",
    "\\b(vercel|vc)\\s+schedules\\b"
  ],
  "importPatterns": [
    "@vercel/schedules"
  ],
  "promptSignals": {
    "phrases": [
      "vercel schedules",
      "@vercel/schedules",
      "handleSchedule",
      "scheduled job",
      "scheduled jobs",
      "scheduled task",
      "recurring job",
      "one-time schedule",
      "migrate cron jobs"
    ],
    "allOf": [
      [
        "vercel",
        "schedule"
      ],
      [
        "vercel",
        "cron"
      ],
      [
        "run",
        "every",
        "hour"
      ],
      [
        "run",
        "every",
        "day"
      ],
      [
        "run",
        "every",
        "night"
      ],
      [
        "send",
        "reminder",
        "later"
      ],
      [
        "per",
        "user",
        "schedule"
      ],
      [
        "schedule",
        "each",
        "user"
      ],
      [
        "vercel",
        "every"
      ]
    ],
    "anyOf": [
      "schedule",
      "cron",
      "recurring",
      "nightly",
      "hourly",
      "timezone",
      "reminder"
    ],
    "noneOf": [
      "schedule a meeting",
      "calendar event",
      "deployment schedule",
      "release schedule"
    ],
    "minScore": 6
  }
}
retrieval
{
  "aliases": [
    "schedules",
    "cron",
    "cron jobs",
    "scheduled functions",
    "recurring jobs",
    "one-time jobs"
  ],
  "intents": [
    "run code on a schedule",
    "run a function every hour",
    "send a reminder at a specific time",
    "create a schedule for each user",
    "migrate cron jobs to schedules",
    "pause or run a schedule now"
  ],
  "entities": [
    "Vercel Schedules",
    "@vercel/schedules",
    "handleSchedule",
    "schedule/v1beta",
    "Schedules.create",
    "vercel schedules"
  ]
}
chainTo
[
  {
    "pattern": "from\\s+['\"](node-cron|cron|croner|node-schedule|agenda)['\"]|cron\\.schedule\\(",
    "targetSkill": "vercel-schedules",
    "message": "In-process cron scheduling detected — it never runs on Vercel, because functions are not long-lived. Loading Vercel Schedules guidance.",
    "skipIfFileContains": "@vercel/schedules"
  },
  {
    "pattern": "\"crons\"\\s*:",
    "targetSkill": "vercel-schedules",
    "message": "Cron Jobs config detected — Schedules replaces Cron Jobs and adds timezones, private targets, and per-environment state. Loading Vercel Schedules guidance.",
    "skipIfFileContains": "\"schedules\"\\s*:"
  }
]

README badge

README badge for vercel/vercel-plugin/vercel-schedules