Job Schedules

Payload's schedule property lets you enqueue Jobs regularly according to a cron schedule - daily, weekly, hourly, or any custom interval. This is ideal for tasks or workflows that must repeat automatically and without manual intervention.

Scheduling Jobs differs significantly from running them:

Queueing: Scheduling only creates (enqueues) the Job according to your cron expression. It does not immediately execute any business logic.
Running: Execution happens separately through your Jobs runner - such as autorun, or manual invocation using payload.jobs.run() or the payload-jobs/run endpoint.

Use the schedule property specifically when you have recurring tasks or workflows. To enqueue a single Job to run once in the future, use the waitUntil property instead.

Example use cases

Regular emails or notifications

Send nightly digests, weekly newsletters, or hourly updates.

Batch processing during off-hours

Process analytics data or rebuild static sites during low-traffic times.

Periodic data synchronization

Regularly push or pull updates to or from external APIs.

Scheduler modes (`jobs.scheduler`)

Payload supports two scheduler modes suitable for different deployment environments:

Mode	When to use	Behaviour
`cron`	Long-running Node environments	Initializes all cron schedules on Payload startup using Croner, regularly evaluating and enqueueing Jobs on time.
`manual`	Ephemeral / serverless environments (Vercel, Netlify, AWS Lambda)	No automatic scheduling occurs. You must explicitly invoke scheduling using `payload.jobs.handleSchedules()` or by calling `/api/payload-jobs/handleSchedules`.

Example configuration:

1export default buildConfig({
2  jobs: {
3    scheduler: process.env.VERCEL ? 'manual' : 'cron',
4  },
5})

Defining schedules on Tasks or Workflows

Schedules are defined using the schedule property:

1export type ScheduleConfig = {
cron: string // required, supports seconds precision
queue: string // required, the queue to push Jobs onto
hooks?: {
  // Optional hooks to customize scheduling behavior
  beforeSchedule?: BeforeScheduleFn
  afterSchedule?: AfterScheduleFn
}
9}

Example schedule

The following example demonstrates scheduling a Job to enqueue every day at midnight:

1import type { TaskConfig } from 'payload'
2
3export const SendDigestEmail: TaskConfig<'SendDigestEmail'> = {
slug: 'SendDigestEmail',
schedule: [
  {
    cron: '0 0 * * *', // Every day at midnight
    queue: 'nightly',
  },
],
handler: async () => {
  await sendDigestToAllUsers()
},
14}

This configuration only queues the Job - it does not execute it immediately. To actually run the queued Job, you configure autorun in your Payload config (note that autorun should not be used on serverless platforms):

1export default buildConfig({
jobs: {
  scheduler: 'cron',
  autoRun: [
    {
      cron: '* * * * *', // Runs every minute
      queue: 'nightly',
    },
  ],
  tasks: [SendDigestEmail],
},
12})

That way, Payload's scheduler will automatically enqueue the job into the nightly queue every day at midnight. The autorun configuration will check the nightly queue every minute and execute any Jobs that are due to run.

Scheduling lifecycle

Here's how the scheduling process operates in detail:

Cron evaluation: Payload (or your external trigger in manual mode) identifies which schedules are due to run. To do that, it will read the payload-jobs-stats global which contains information about the last time each scheduled task or workflow was run.
BeforeSchedule hook:

The default beforeSchedule hook checks how many active or runnable jobs of the same type that have been queued by the scheduling system currently exist. If such a job exists, it will skip scheduling a new one.
You can provide your own beforeSchedule hook to customize this behavior. For example, you might want to allow multiple overlapping Jobs or dynamically set the Job input data.

Enqueue Job: Payload queues up a new job. This job will have waitUntil set to the next scheduled time based on the cron expression.
AfterSchedule hook:

The default afterSchedule hook updates the payload-jobs-stats global metadata with the last scheduled time for the Job.
You can provide your own afterSchedule hook to it for custom logging, metrics, or other post-scheduling actions.

Customizing concurrency and input (Advanced)

You may want more control over concurrency or dynamically set Job inputs at scheduling time. For instance, allowing multiple overlapping Jobs to be scheduled, even if a previously scheduled job has not completed yet, or preparing dynamic data to pass to your Job handler:

1import { countRunnableOrActiveJobsForQueue } from 'payload'
2
3schedule: [
{
  cron: '* * * * *', // every minute
  queue: 'reports',
  hooks: {
    beforeSchedule: async ({ queueable, req }) => {
      const runnableOrActiveJobsForQueue =
        await countRunnableOrActiveJobsForQueue({
          queue: queueable.scheduleConfig.queue,
          req,
          taskSlug: queueable.taskConfig?.slug,
          workflowSlug: queueable.workflowConfig?.slug,
          onlyScheduled: true,
        })
17
      // Allow up to 3 simultaneous scheduled jobs and set dynamic input
      return {
        shouldSchedule: runnableOrActiveJobsForQueue < 3,
        input: { text: 'Hi there' },
      }
    },
  },
},
26]

This allows fine-grained control over how many Jobs can run simultaneously and provides dynamically computed input values each time a Job is scheduled.

Scheduling in serverless environments

On serverless platforms, scheduling must be triggered externally since Payload does not automatically run cron schedules in ephemeral environments. You have two main ways to trigger scheduling manually:

Invoke via Payload's API: payload.jobs.handleSchedules()
Use the REST API endpoint: /api/payload-jobs/handleSchedules
Set the run REST API to trigger scheduling: POST /api/payload-jobs/run?handleSchedules=true

For example, on Vercel, you can set up a Vercel Cron to regularly trigger scheduling:

Vercel Cron Job: Configure Vercel Cron to periodically call GET /api/payload-jobs/handleSchedules. If you already have vercel cron set up for auto-running, you can also append ?handleSchedules=true to the run endpoint to trigger scheduling.

Once Jobs are queued, their execution depends entirely on your configured runner setup (e.g., autorun, or manual invocation).

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Job Schedules

Example use cases

Scheduler modes (`jobs.scheduler`)

Defining schedules on Tasks or Workflows

Example schedule

Scheduling lifecycle

Customizing concurrency and input (Advanced)

Scheduling in serverless environments

Query Presets

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

See what others are building with Payload.

"Payload has transformed the way our clients manage content. It's an indispensable tool for any modern agency."

Get the resources you need to start building today

Microsoft chose Payload to tell the world about AI.

Job Schedules

Example use cases

Scheduler modes (jobs.scheduler)

Defining schedules on Tasks or Workflows

Example schedule

Scheduling lifecycle

Customizing concurrency and input (Advanced)

Scheduling in serverless environments

Query Presets

Scheduler modes (`jobs.scheduler`)