A cron job runs your command on a schedule, inside the same plan or Usage Billing placement as the rest of your app. Add one from an application’s Cron Jobs tab, or with POST /api/v1/apps/{uuid}/cronjobs.

Sizing a run

Every cron job runs at a size - the same size codes a resource plan or Usage Billing workload uses, in the application’s own CPU class (Hobby or Pro). List what is available for an application with GET /api/v1/apps/{uuid}/cronjobs/sizes, which also gives each size’s price per minute - a resource plan’s monthly price divided by 43,200 minutes. Leaving size out on create picks the smallest size with at least the application’s RAM, whatever its CPU - or the largest size of the class if none has that much, rather than defaulting to the smallest size on offer. If a resource’s plan changes and a cron job’s size is no longer sold in the new CPU class, it moves to the size that best fits its application. A cron job never takes RAM from its resource: each run is a pod of its own, on any resource, and only its cron minutes limit it. A cron job is billed for the seconds each run takes, at its size’s price - whether the application runs on a resource or on Usage Billing.

Included cron minutes

Every paid resource plan includes 1,000 cron minutes a billing cycle, at the plan’s own size, shared by every cron job on that resource. A run at a different size counts against those minutes by its own price per minute - a $29 plan’s 1,000 minutes, for example, are worth more minutes at a smaller size and fewer at a larger one. Nothing carries over to the next cycle. Find how many minutes a resource has left on its page, or with GET /api/v1/resources/{uuid}, under cron_minutes:
Workspace admins are emailed once a cycle at 75% and at 100% of a resource’s included minutes; see Workspace limits for the enterprise case.

Choosing what happens once they run out

Each cron job has its own overage setting, changed on create or update:
  • pause (the default) - the cron job pauses until the next renewal resets the resource’s minutes; a run already under way finishes. Resuming it by hand before then is refused.
  • bill - it keeps running, and every run past the included minutes is billed by the second at its size’s price, on Usage Billing. Choosing bill needs the apps:manage permission, and - on a resource whose workspace is not otherwise paying for Usage Billing - starts the $5 monthly minimum first.
A cron job on Usage Billing, or on a plan that costs nothing, has no minutes to run out of - every run is simply billed. On an enterprise contract a cron job always pauses at its limit; nothing is billed.
Creating a cron job only starts the $5 monthly minimum when you set overage to bill, or when the application’s resource is on a plan with no included cron minutes (every run billed from the first). Creating one with the default pause on a resource that already has minutes starts nothing.

Stopping a run that takes too long

Set max_run_seconds (1 second to 24 hours) on create or update, in the dashboard in minutes. A run still going past it is stopped and recorded as a failed run with reason DeadlineExceeded. Leave it out, or send null, for no limit.

Run history

The cron job’s Last run column, and its Job History view, show whether each run succeeded or failed, how long it took, and - for a failed run - why (DeadlineExceeded, BackoffLimitExceeded, or the container’s own exit reason such as OOMKilled). The same history is at GET /api/v1/apps/{uuid}/cronjobs/{id}/runs, newest first; the latest 100 runs are kept. A failed run opens a cronjob_failed issue on the cron job - it keeps its schedule, and the next run that succeeds resolves the issue.

Pausing and resuming

Pause a cron job from the dashboard, or with POST /api/v1/apps/{uuid}/cronjobs/{id}/pause; resume it with the matching /resume endpoint. A paused cron job starts no new run - one already under way finishes - and it is not billed and holds no room on its resource while paused.

Next steps

Usage Billing

Running a cron job without a resource.

Workspace limits

How cron minutes fit into the rest of the workspace’s limits.

Issues

The history behind a failed run.