Intermediate
How to add cron jobs on Vercel
Quick Answer
Configure Vercel cron jobs in
vercel.json with a crons array specifying path and schedule cron expression, create a matching API route endpoint, deploy to production, and monitor in the dashboard. Free tier limits to 1-2 jobs with daily frequency; use Pro for more. Design handlers as idempotent and secure with CRON_SECRET.Prerequisites
- Vercel account and project linked to Git
- Serverless or Edge Function API route knowledge
- Basic cron expression syntax
- Familiarity with Vercel deployments
- Node.js or TypeScript for handlers
1
Create Serverless or Edge Function endpoint
Add a function file at the path you'll reference, such as
api/cron.ts or app/api/cron/route.ts in Next.js. This handles cron invocations via HTTP GET. Example for Node.js: import type { VercelRequest, VercelResponse } from '@vercel/node';
export default function handler(req: VercelRequest, res: VercelResponse) {
// Your task logic here (make idempotent for duplicates)
res.status(200).json({ success: true });
}/; test locally with curl http://localhost:3000/api/cron.Tip
Design for idempotency using unique IDs or timestamps to handle potential duplicates safely.
2
Secure the cron endpoint
Add an environment variable
CRON_SECRET (random 16+ chars) in Vercel dashboard. Check Authorization header in handler: const authHeader = req.headers.authorization;
if (!process.env.CRON_SECRET || authHeader !== `Bearer ${process.env.CRON_SECRET}`) {
return res.status(401).json({ success: false });
}
// Proceed with task3
Configure vercel.json at project root
Create or edit
vercel.json with crons array. Each job needs path (starts with /, e.g. "/api/cron") and schedule (5-field cron string, UTC). Example for daily 5 AM: {
"crons": [
{
"path": "/api/cron",
"schedule": "0 5 * * *"
}
]
}"0 0 * * *", hourly "0 * * * *".Tip
Validate cron syntax; Hobby limits to once/day max, expressions fail otherwise.
4
Deploy to production
Push to production branch (e.g.
main) for auto-deploy, or use CLI vercel --prod. Crons activate only on production deployments (previews ignored). Invocations hit your prod URL like https://your-project.vercel.app/api/cron. Post-build, jobs are live.Tip
Use production domain; preview branches skip crons entirely.
5
Verify in Vercel Dashboard
Log in at vercel.com/dashboard, select Project > Settings > Cron Jobs tab. Lists active jobs with paths/schedules/next run. Click View Logs to filter logs by
requestPath:/api/cron.6
Monitor and test locally
Test endpoint locally:
curl http://localhost:3000/api/cron (prod skips redirects). Dashboard shows invocations, errors. Jobs non-concurrent by default; duration matches Function limits.Tip
Cron accuracy: Hobby ~1-hour window; Pro more precise.
7
Update or disable crons
Edit
vercel.json (change schedule/path or remove), redeploy. Or use dashboard Disable Cron Jobs button (re-enable via redeploy). Changes reflect post-deploy.Tip
Pro/Enterprise: Up to 40/100 jobs, unlimited frequency.
8
Handle concurrency and idempotency
Design tasks idempotent: use IDs/timestamps, check state before changes. Combine with locks for reliability. Avoid side effects on duplicates.
Troubleshooting
Cron not triggering or no dashboard entry
Ensure production deployment (previews ignored); redeploy via Git push to main or
vercel --prod. Check Cron Jobs tab.Build fails with invalid config
Validate
vercel.json JSON and cron syntax (5 fields, path starts with /). Hobby: once/day max.401 Unauthorized on invocation
Set
CRON_SECRET env var and verify Authorization: Bearer ${process.env.CRON_SECRET} in handler.Timeouts or cold starts
Optimize handler; add
?__no_cache=1 query if cached. Upgrade to Pro for better reliability.Frequent jobs fail on Hobby
Free/Hobby limits 1-2 jobs, daily only. Upgrade to Pro for up to 40 jobs, any frequency.
Ready to get started with Vercel?
Put this tutorial into practice. Visit Vercel and follow the steps above.
Visit Vercel →