LuaJob

LuaJob defines a job: an execute function the platform runs on a schedule, outside any conversation. Register jobs on LuaAgent.jobs; lua push job uploads a version, lua deploy job makes it live, and lua jobs activate and lua jobs deactivate start and pause the schedule. For a job created at runtime from a tool, such as a reminder for one end user, use Jobs.create instead. Verified against lua-cli 3.33.0.

import { LuaJob } from 'lua-cli';

Quick example

src/jobs/DailyDigestJob.ts

import { LuaJob, Data } from 'lua-cli';

export default new LuaJob({
  name: 'daily-digest',
  description: 'Count open tickets every morning and store the total',
  schedule: { type: 'cron', expression: '0 9 * * *', timezone: 'Europe/London' },
  timeout: 120,
  retry: { maxAttempts: 3, backoffSeconds: 60 },
  async execute(job) {
    const open = await Data.get('tickets', { status: { $eq: 'open' } }, 1, 1);
    return { jobName: job.name, openTickets: open.pagination.totalCount };
  },
});

Run it once locally, without waiting for the schedule.

lua test job --name daily-digest

Output

…
✅ Job execution successful!

Job returned: Object — fields: jobName, openTickets
Output:
{ jobName: 'daily-digest', openTickets: 0 }
✨ Job works locally. To test in production:
   Trigger now:   `lua jobs trigger --job-name daily-digest`
   Inspect logs:  `lua logs --type job --name daily-digest --limit 5`

Constructor

new LuaJob(config: LuaJobConfig)

string

required

Server-side identifier, kebab-case. Also --name for lua push job and lua test job, and --job-name for lua jobs.

string

required

One or two sentences shown in listings.

JobSchedule

required

When the job runs; see Schedules. Write it as an object literal or a constant the compiler can evaluate.

(job: JobInstance) => Promise<any>

required

The function the platform runs. Its return value is stored on the execution.

number

default:"300"

Maximum run time in seconds. An integer from 1 to 600.

{ maxAttempts: number; backoffSeconds?: number }

Retry policy for a failed attempt; see Execution. Without it a failed occurrence isn’t retried.

{ maxSilenceMinutes?: number; alertAfterConsecutiveFailures?: number; notify?: 'app' | 'email' | 'emailApp' }

Alert the job’s owner when no execution has succeeded for maxSilenceMinutes (5–43 200, recurring schedules only, longer than an interval period) or after alertAfterConsecutiveFailures failed executions in a row (1–50). notify defaults to emailApp. Give at least one threshold. lua jobs view shows a Health line. Compiling it needs the next lua-cli release; an older CLI drops it. See Watch schedule health.

Record<string, any>

Static data available inside execute as job.metadata. The place for an end user ID the job should act for.

The constructor throws when:

name is empty or blank: LuaJob requires a non-empty `name` (used as the server-side identifier).
timeout is not an integer: LuaJob `timeout` must be an integer number of seconds.
timeout is outside 1 to 600: LuaJob `timeout` must be between 1 and 600 seconds.

lua compile fails with Job must have an execute function, Job must have a schedule when it can’t evaluate the schedule, and Invalid schedule type: <type>. Must be one of: cron, interval, once.

As a subclass

A job can also be a class that extends LuaJob, declaring name, description, schedule and execute as its own members; register the class on LuaAgent.jobs, not an instance.

src/jobs/DailyDigestJob.ts

import { LuaJob } from 'lua-cli';

export class DailyDigestJob extends LuaJob {
  name = 'daily-digest';
  description = 'Count open tickets every morning and store the total';
  schedule = { type: 'cron' as const, expression: '0 9 * * *' };
  async execute(job: any) {
    return { jobName: job.name };
  }
}

A subclassed job must declare its own execute. One that declares none now fails the build with Job must have an execute function, where it used to compile and then throw the first time the platform ran the schedule. Inheriting execute from a base class you wrote still counts as declaring it; what the class inherits from LuaJob itself does not.

Schedules

JobSchedule is a union of three shapes.

`type`	Fields	Example
`'cron'`	`expression`: five-field cron; `timezone?`: IANA name	`{ type: 'cron', expression: '0 9 * * 1-5', timezone: 'America/New_York' }`
`'once'`	`executeAt`: `Date` or ISO 8601 string	`{ type: 'once', executeAt: '2026-12-31T10:00:00Z' }`
`'interval'`	`seconds`: number	`{ type: 'interval', seconds: 900 }`

Execution

execute receives a JobInstance with id, name, metadata, activeVersion, and data, plus updateMetadata(), delete(), trigger(), activate(), and deactivate(); the members are listed on Jobs. job.user() resolves to the user recorded on the job; for a declared LuaJob that is the developer whose push created it, not an end user, and it throws User API not initialized when the job has no recorded end user. To act for an end user, read an ID from metadata and call User.get(userId). Each scheduled occurrence runs at least once. When an attempt fails or times out and retry is set, the platform retries while maxAttempts allows: each retry waits a fixed backoffSeconds (60 when omitted or 0), with no jitter, and the platform stops after 10 attempts whatever maxAttempts says. Retries of one occurrence never run concurrently.

Deployed runs only. job.execution is undefined in lua test; every deployed run sets it to { executionId, attempt, occurrenceId, scheduledTime? }, which isn’t on the JobInstance type yet, so read it through a widened type and key side effects on occurrenceId.

type JobExecutionMeta = { executionId: string; attempt: number; occurrenceId: string; scheduledTime?: string };

const execution = (job as typeof job & { execution?: JobExecutionMeta }).execution;

Methods

Read-only getters that return what was passed to the constructor, and a way to run the handler in a test.

Method	Returns
`getName()`	`string`
`getDescription()`	`string`
`getSchedule()`	`JobSchedule`
`getTimeout()`	`number`, the resolved timeout in seconds
`getRetry()`	`{ maxAttempts: number; backoffSeconds?: number } \| undefined`
`getMetadata()`	`Record<string, any> \| undefined`
`execute(job: JobInstance)`	`Promise<any>`, the handler’s return value

Types

LuaJobConfig and JobSchedule are exported types; JobInstance is an exported class.

import type { LuaJobConfig, JobSchedule } from 'lua-cli';

const nightly: JobSchedule = { type: 'cron', expression: '0 2 * * *', timezone: 'UTC' };

SDK

CLI

REST API

Quick example

Constructor

As a subclass

Schedules

Execution

Methods

Types

See also

​Quick example

​Constructor

​As a subclass

​Schedules

​Execution

​Methods

​Types

​See also

Quick example

Constructor

As a subclass

Schedules

Execution

Methods

Types

See also