Skip to Content

Cron

Three tools, cron_jobs, cron_runs and cron_control, let the agent list deployed scheduled jobs, read their run history, run a job now, pause it or resume its schedule.

A scheduled job is a file app/<folder>/<name>.cron.ts with export const schedule (UTC) and a default function. Deploy registers the schedule; a failed run is retried up to 3 times.

cron_jobs

Lists the deployed jobs.

  • Parameters: project; env: preview or prod to filter; both by default.
  • Returns: each job’s id, schedule (UTC), paused, next run and last run. No jobs returns an empty list with a note.
  • When the agent calls it: after a deploy, to confirm the schedule was registered and to get the job_id.

cron_runs

The run history of one job, newest first.

  • Parameters: project; job_id; limit: 1–200, default 20.
  • Returns: each run’s status, duration and error, if any.
  • When the agent calls it: when a job doesn’t do what it should, or after cron_control with run.

cron_control

Controls one job.

  • Parameters: project; job_id; action:
    • run: runs the job once now, even while paused. Returns a run_id; about 10 seconds later the result is in cron_runs.
    • pause: stops scheduled runs.
    • resume: restarts them.
  • Returns: run_id for run; paused for pause and resume.
  • When the agent calls it: to test a newly deployed job without waiting for its time, or to stop a job that sends the wrong emails.

A pause is kept across deploys. Each run executes the app’s real code, which may send email or call outside services.

Next steps

Last updated