Jobs

Now that we have covered Tasks and Workflows, we can tie them together with a concept called a Job.

For example, let's say we have a Workflow or Task that describes the logic to sync information from Payload to a third-party system. This is how you'd declare how to sync that info, but it wouldn't do anything on its own. In order to run that task or workflow, you'd create a Job that references the corresponding Task or Workflow.

Jobs are stored in the Payload database in the payload-jobs collection, and you can decide to keep a running list of all jobs, or configure Payload to delete the job when it has been successfully executed.

Queuing a new job

In order to queue a job, you can use the payload.jobs.queue function.

Here's how you'd queue a new Job, which will run a createPostAndUpdate workflow:

1const createdJob = await payload.jobs.queue({
// Pass the name of the workflow
workflow: 'createPostAndUpdate',
// The input type will be automatically typed
// according to the input you've defined for this workflow
input: {
  title: 'my title',
},
overrideAccess: true,
10})

In addition to being able to queue new Jobs based on Workflows, you can also queue a job for a single Task:

1const createdJob = await payload.jobs.queue({
task: 'createPost',
input: {
  title: 'my title',
},
overrideAccess: true,
7})

Where to Queue Jobs

Jobs can be queued from anywhere in your application. Here are the most common scenarios:

From Collection Hooks

The most common place - queue jobs in response to document changes:

1{
slug: 'posts',
hooks: {
  afterChange: [
    async ({ req, doc, operation }) => {
      // Only send notification for published posts
      if (operation === 'update' && doc.status === 'published') {
        await req.payload.jobs.queue({
          task: 'notifySubscribers',
          input: {
            postId: doc.id,
          },
          overrideAccess: true,
        })
      }
    },
  ],
},
19}

From Field Hooks

Queue jobs based on specific field changes:

1{
name: 'featuredImage',
type: 'upload',
relationTo: 'media',
hooks: {
  afterChange: [
    async ({ req, value, previousValue }) => {
      // Generate image variants when image changes
      if (value !== previousValue) {
        await req.payload.jobs.queue({
          task: 'generateImageVariants',
          input: {
            imageId: value,
          },
          overrideAccess: true,
        })
      }
    },
  ],
},
21}

From Custom Endpoints

Queue jobs from your API routes:

1export const POST = async (req: PayloadRequest) => {
const job = await req.payload.jobs.queue({
  workflow: 'generateMonthlyReport',
  input: {
    month: new Date().getMonth(),
    year: new Date().getFullYear(),
  },
  overrideAccess: false,
  req,
})
11
return Response.json({
  message: 'Report generation queued',
  jobId: job.id,
})
16}

From Server Actions

Queue jobs from Next.js server actions:

1'use server'
2
3import { headers } from 'next/headers'
4import { createLocalReq, getPayload, UnauthorizedError } from 'payload'
5import config from '@payload-config'
6
7export async function scheduleEmail() {
8  const payload = await getPayload({ config })
9  const { user } = await payload.auth({ headers: await headers() })
10
11  if (!user) {
12    throw new UnauthorizedError()
13  }
14
15  const req = await createLocalReq({ user }, payload)
16
17  await payload.jobs.queue({
18    task: 'sendEmail',
19    input: { userId: user.id },
20    overrideAccess: false,
21    req,
22  })
23}

Job Options

When queuing a job, you can pass additional options:

1await payload.jobs.queue({
task: 'sendEmail',
input: { userId: '123' },
overrideAccess: true,
5
// Schedule the job to run in the future
waitUntil: new Date('2024-12-25T00:00:00Z'),
8
// Assign to a specific queue
queue: 'high-priority',
11
// Add custom metadata for tracking
log: [
  {
    message: 'Email queued by admin',
    createdAt: new Date().toISOString(),
  },
],
19})

Common options

waitUntil - Schedule the job to run at a specific date/time in the future
queue - Assign the job to a specific queue (defaults to 'default')
log - Add custom log entries for debugging or tracking
req - Pass the request context for access control
overrideAccess - Skip Jobs access control when set to true (defaults to false)

Check Job Status

After queuing a job, you can check its status:

1const job = await payload.jobs.queue({
2  task: 'processPayment',
3  input: { orderId: '123' },
4  overrideAccess: true,
5})
6
7// Later, check the job status
8const updatedJob = await payload.findByID({
9  collection: 'payload-jobs',
10  overrideAccess: true,
11  id: job.id,
12})
13
14console.log(updatedJob.completedAt) // When it finished
15console.log(updatedJob.hasError) // If it failed
16console.log(updatedJob.taskStatus) // Details of each task

Job Status Fields

Each job document contains:

1{
id: 'job_123',
taskSlug: 'sendEmail',        // Or workflowSlug for workflows
input: { userId: '123' },     // The input you provided
completedAt: '2024-01-15...',  // When job completed (null if pending)
hasError: false,              // True if job failed
totalTried: 1,                // Number of attempts
processingUntil: null,        // Future date while a worker owns the job
processingToken: null,        // Internal token for the current owner
taskStatus: {                 // Status of each task (for workflows)
  sendEmail: {
    '1': {
      complete: true,
      output: { emailSent: true }
    }
  }
},
log: [                        // Execution log
  {
    message: 'Job started',
    createdAt: '...'
  }
]
24}

Payload increments totalTried after each completed attempt. While the handler runs, Payload automatically renews processingUntil. The claim also gets a processingToken, and worker updates only start while that token still matches and enough lease time remains for the configured safety buffer. If the worker disappears, the lease expires and a later jobs runner call can claim the job again. A crashed worker does not increment totalTried or consume a handler retry.

Access Control

Use Payload's dedicated Jobs APIs and endpoints, such as payload.jobs.*, /run, and /handle-schedules. Calling generic Local API, REST, or GraphQL CRUD directly on payload-jobs is not recommended because it bypasses the job operations and does not run jobs.access.*.

Raw collection create, read, update, and delete access is denied by default. You can adjust these rules through jobsCollectionOverrides. REST, GraphQL, and Local API CRUD run these access rules by default. Set overrideAccess: true only for trusted server-side operations that should bypass them.

The dedicated job operations use jobs.access.queue, run, and cancel. payload.jobs.queue(), run(), runByID(), cancel(), and cancelByID() run these functions by default because their overrideAccess option defaults to false. Set overrideAccess: true to bypass Jobs access control for trusted server-side work. The /run and /handle-schedules endpoints always check jobs.access.run.

Configure access for the dedicated job operations in your Jobs Config:

1import type { SanitizedConfig } from 'payload'
2
3const config: SanitizedConfig = {
// ...
jobs: {
  access: {
    // Control who can queue new jobs
    queue: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
    // Control who can run jobs
    run: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
    // Control who can cancel jobs
    cancel: ({ req }) => {
      return req.user?.roles?.includes('admin')
    },
  },
},
21}

These functions receive the current req and return a boolean. By default, they allow authenticated users.

Omit overrideAccess or pass overrideAccess: false to run them from the Local API:

1const req = await createPayloadRequest({ payload, user })
2
3await payload.jobs.queue({
4  workflow: 'createPost',
5  input: { title: 'My Post' },
6  overrideAccess: false, // Enable access control
7  req, // Pass the request with user context
8})

Cancelling Jobs

Payload allows you to cancel jobs that are either queued or currently running. When cancelling a running job, the current task will finish executing, but no subsequent tasks will run. This happens because the job checks its cancellation status between tasks.

To cancel a specific job, use the payload.jobs.cancelByID method with the job's ID:

1await payload.jobs.cancelByID({
2  id: createdJob.id,
3  overrideAccess: true,
4})

To cancel multiple jobs at once, use the payload.jobs.cancel method with a Where query:

1await payload.jobs.cancel({
overrideAccess: true,
where: {
  workflowSlug: {
    equals: 'createPost',
  },
},
8})

From within a task or workflow handler, you can also cancel the current job by throwing a JobCancelledError:

1throw new JobCancelledError('Job was cancelled')

Was this page helpful?

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.