Scheduled Jobs

A Scheduled Job runs a task automatically at the times you choose, such as generating a report every night or cleaning up old data every hour. You do not need to keep an application running all the time: Zenifra starts the task on schedule, tracks the run, and charges only for the time it actually ran.

This guide shows how to use Jobs in the Console. To automate with the API or the CLI, see the Scheduled Jobs API reference.

How it works

  • UTC schedule: the schedule is set by a five-field Cron expression and is always interpreted in UTC.
  • At most one run at a time: if the next scheduled time arrives while a run is still in progress, that time is skipped. It is not queued or run later.
  • 60-minute limit: a run that does not finish within 60 minutes is stopped and shows as Time limit exceeded.
  • No automatic retry: if a run fails, Zenifra does not try again for that time. The next run happens at the next scheduled time.
  • Per-minute billing: you pay for the time the task actually ran, in BRL.

Create a Job in the Console

Video: creating a Scheduled Job, from the form to the page with schedule and runs.

  1. In the menu, click Create project and choose Scheduled Job.
  2. Choose your plan. Each plan shows its resources (vCPU, memory, and storage) and its price per minute. You can change the plan later without recreating the Job (see Job plan).
  3. Under Basic Information, give the project a name.
  4. Under Configure Scheduled Job, fill in:
    • Task source: choose OCI Image or GitHub Repository.
    • With OCI Image, enter the Task image: the full reference of a public Docker image, with a registry and a tag or digest (for example, docker.io/library/alpine:3.20). On creation, the Console uses the image's own default command, so it must run the task and finish on its own; later, you can change it under Run command.
    • With GitHub Repository, choose the repository, Branch, Runtime (Node.js, Python, Bun, Go, Java, or PHP), Version, Root directory, and Task command. See Use a GitHub repository.
    • Cron expression: five fields, in UTC. Right below, the Console shows the Next execution times (UTC) so you can check them.
    • Task storage: turn on Keep data between runs and enter the Capacity (GB) and the Persistent directory (for example, /data) if the task needs to keep files from one run to the next. Otherwise, each run uses the temporary disk included in the plan.
  5. Under Environment Variables, add the settings the task uses, such as keys and addresses. Empty rows are ignored.
  6. Review the Cost Summary and click Create Job.

Scheduled Job plans with per-minute billing

Task image with a pinned version and cron expression highlighted

Cost Summary with the Create Job button highlighted

The Console does not ask for a port, domain, or instances, because a Job is not a website or an API: it runs, finishes, and waits for the next scheduled time.

To use a private image, create the Job through the API. To use a command and arguments other than the image defaults, create the Job and set them under Run command.

Use a GitHub repository

With GitHub Repository, Zenifra builds your code and uses the result in every run. If GitHub is not connected to your account yet, the Console shows how to connect it before listing repositories.

  • Root directory: the repository folder that holds the task. Use . for the root.
  • Task command: the command run at each scheduled time, for example node src/index.js. It must finish on its own, just like an image. Zenifra runs this command directly, so the task receives the stop notice when a run is cancelled, paused, or deleted; in a command chained with && or ;, this applies to the last step. Commands with | or || don't receive that notice, so prefer calling a script.
  • Deployment mode: sets when a new build happens: Manual, Automatic by branch (on every push to the branch), By Tag, or By Release.

The first build happens on creation, and the Job starts running on schedule after it finishes. Later builds are listed under Build logs on the project page, which also has the New build button. A new build applies to the next runs and does not interrupt a run in progress.

Build time is not charged: billing only counts the time the task runs.

To get started, use the Scheduled Job examples in Node.js, Bun, and Python, which already follow these recommendations.

Schedule examples

When to runCron expression
Every 15 minutes*/15 * * * *
Every hour, at minute 00 * * * *
Every day at 03:00 (UTC)0 3 * * *
Monday to Friday at 12:30 (UTC)30 12 * * 1-5
On the 1st of every month at 06:00 (UTC)0 6 1 * *

Remember to convert your local time to UTC. For example, midnight in Brasília time (UTC−3) is 03:00 UTC.

The expression accepts values, *, lists (,), ranges (-), steps (/), English month and weekday names (jan, mon), and ? in the day of month or day of week. Day of week goes from 0 (Sunday) to 6; 7, L, W, #, and H are not accepted. See the full format in the Scheduled Jobs API.

Turn off a team's projects at a set time

A Job can pause the projects of a team every day at a set time, for example at 8 PM, and another one can resume them the next morning. That way the organization does not pay for the projects outside the hours they are used.

  1. In API Keys, create a key with the View project and Stop project permissions (and Resume project, if you will turn them back on). Whoever creates the key limits its reach: a maintainer's key only reaches the projects that maintainer can already operate. See API Keys.
  2. In one of your GitHub repositories, create the file below.
  3. Create a scheduled Job with no team, using GitHub Repository, the Node.js 22 or newer runtime and the Task command node pause-team.mjs.
  4. Use the Cron expression of the time in UTC. To pause at 8 PM Brasília time from Monday to Friday: 0 23 * * 1-5.
  5. Under Environment Variables, add ZENIFRA_API_KEY (the key from step 1) and TEAM_NAME (the team name, exactly as shown in Teams).
pause-team.mjs
// Pauses the projects of a team. With ACTION=resume, resumes the paused ones.
const api = 'https://api.zenifra.com/v1'
const headers = { Authorization: `Bearer ${process.env.ZENIFRA_API_KEY}` }
const resume = process.env.ACTION === 'resume'

const call = async (path, method = 'GET') => {
  const response = await fetch(`${api}${path}`, { method, headers })
  if (!response.ok) throw new Error(`${method} ${path} answered ${response.status}`)
  return response.json()
}

const targets = []
for (let page = 1, pages = 1; page <= pages; page += 1) {
  const { data } = await call(`/project?page=${page}&limit=50`)
  pages = data.pagination.pages
  for (const project of data.projects) {
    if (project.owner_team?.name !== process.env.TEAM_NAME) continue
    if (resume ? project.status === 'stopped' : ['running', 'failing'].includes(project.status)) targets.push(project)
  }
}

for (const project of targets) {
  await call(`/project/${project.id}/${resume ? 'resume' : 'stop'}`, 'PATCH')
  console.log(`${resume ? 'Resumed' : 'Paused'}: ${project.name}`)
}
console.log(`${targets.length} project(s) of team ${process.env.TEAM_NAME}`)

To turn them back on, create a second Job with the same repository and the variable ACTION=resume, at the time they should come back (for example, 0 10 * * 1-5 for 7 AM Brasília time).

The pause is the same as the project's Pause button: nothing is deleted, and the project's hourly billing stops while it is paused. Anyone with access to the project can resume it earlier.

How a run's result is decided

The result depends on how your image's process ends:

  • exit code 0 means success, and the run shows as Succeeded;
  • any non-zero exit code means failure, and the run shows as Failed; code 1 is only the most common example;
  • if the process does not finish within 60 minutes, the run shows as Time limit exceeded.

Web server images, which keep waiting for requests, never finish on their own and always end in Time limit exceeded. For a Job, use an image whose default command runs the routine and exits.

Monitor runs

Project list with the Job and the Open button highlighted

Job page with schedule, runs and current cycle cost

The project page brings together everything that happens with your Job.

Job schedule

The Job schedule card shows the current cron expression and the time zone (UTC). Click Edit to change the schedule; the change applies to the next runs.

Environment variables

Click Edit and, under Environment variables, change, add, or remove variables, then click Save environment variables. The change applies to the next runs: a run in progress keeps the previous values, and a removed variable no longer exists from the following run on.

Job plan

Click Edit and, in the Job plan card, pick another plan from the list (each option shows its price per minute), then click Save plan. The plan sets the CPU, memory and temporary disk of each run and the price per minute. The new plan applies from the next run; a run in progress finishes on the current plan.

The change does not run a new build or recreate the Job: the schedule, the command, the variables, and the run history stay the same. You can also change the plan while the Job is paused. If the organization has pending payments, you can only move to a cheaper plan. To decide which plan to use, see Which plan to choose for Scheduled Jobs.

Run command

On a Job with OCI Image, click Edit and use the Run command card to override the image's command (ENTRYPOINT) and arguments (CMD), without a new build:

  • Command: the program the run starts, for example python;
  • Arguments: what comes after it, for example manage.py, send_reports, and --daily.

Write one item per line, without quotes; blank lines are ignored. The command runs directly, without a shell, so &&, |, and variables such as $HOME are not interpreted: to chain steps, call a script from the image. Leave a field empty to go back to the image's default and click Save command. The change applies from the next run; a run in progress keeps the previous command.

On a Job with GitHub Repository, this card does not appear: the Task command lives in the Git repository section of the project page.

Run list

The Runs card lists the runs in the current billing cycle, with:

  • Scheduled for: the scheduled time;
  • Status: the state of the run;
  • Duration: how long the task ran;
  • Billed minutes: the minutes used to calculate the amount.

Click Refresh runs to see what is new. The possible statuses are:

StatusWhat it means
RunningThe task is running now.
SucceededThe process finished with exit code 0.
FailedThe process finished with a non-zero exit code. If the run reached the memory limit of the plan, it shows below: Out of memory: the run reached the memory limit of the plan. If it wrote more than the temporary disk of the plan, it shows: Out of disk: the run wrote more than the temporary storage of the plan.
Time limit exceededThe process did not finish within 60 minutes.
CancelledThe run was cancelled by someone in the organization or by pausing/deleting the Job.

Logs

Click View logs on a run to read what the task wrote during that run. Logs help you understand a failure or confirm what was processed.

Logs stay available after a run finishes, fails, exceeds the time limit, or is cancelled, including what the task wrote while it was being stopped. Zenifra keeps the last 50 KB of log for each run.

Metrics

Click View metrics to follow the run's CPU and memory usage. While it runs, the Console shows Collecting metrics with the latest values; after it finishes, it shows the average and peak. Metrics unavailable means there were not enough samples (for example, in runs of a few seconds) — it does not mean zero usage.

Per-run metrics are part of the job-premium plan. On other plans, the View metrics button does not appear. Besides the plan, the person needs the View metrics permission.

Email alerts

Every scheduled Job is created with email alerts on. The organization owner receives an email when a run ends with an error, is stopped for reaching the memory limit or the temporary disk of the plan, or goes past the 60-minute limit. While failures continue, at most one email per hour is sent. To turn them off, click Edit and use the Email alerts card. See the details in Observability.

Cancel, pause, resume, and delete

Cancel a run

In the run list, click Cancel run on the run in progress and confirm. Zenifra gives the task up to 30 seconds to finish gracefully and, if it does not, performs a forced cleanup.

Billing stops at the moment you confirmed the cancellation; the shutdown seconds are not charged. Cancelling a run does not change the schedule: the next run happens as usual.

Pause and resume

Click Pause and confirm with Pause project to stop the next scheduled times. If a run is in progress, it is also cancelled, billed up to the moment of the pause. To run on schedule again, click Resume.

Delete a Job

Click Delete and confirm. If a run is in progress, it is cancelled and billed up to the moment of deletion, and then the project is removed. If you see a message that runs are still being finalized, wait a moment and try again — there is no need to retry repeatedly.

Permissions

Each Console action depends on a permission in the person's role in the organization. Permissions are configured on the Members screen, in the Projects section:

In the ConsoleRequired permission
Create a JobCreate project
Open the Job, see its schedule and run listView project
View logs of a runView logs
View metrics of a run (job-premium plan)View metrics
See the Current cycle costView costs
Edit the Job scheduleUpdate schedule
Save plan in the Job plan cardAllow plan change
Save command in the Run command cardUpdate schedule
See the Job's Environment variablesView environment
Save environment variablesUpdate environment
Cancel runCancel Scheduled Job runs
Pause the JobStop project
Resume the JobResume project
Delete the JobDelete project

When a permission is missing, the Console hides or disables the matching action and tells you that your access does not include it.

Billing

Price per minute

Scheduled Jobs are billed per minute only; there is no hourly, monthly, or yearly billing for this project type. Each plan has a price per minute, in BRL, shown in the Console when you choose the plan. Because the amounts are fractions of a cent, the Console shows up to six decimal places for the per-minute price and up to four for amounts and totals — for example, R$ 0.000167 per minute.

How minutes are counted

  • Billing uses the task's real start and finish. Preparation time, such as the image download, is not charged, and a run that never started creates no charge.
  • The duration is rounded up to the next full minute, with a minimum of 1 minute and a maximum of 60.
  • Each run's amount is stored exactly, never rounded up: a run that costs R$ 0.0005 is charged as R$ 0.0005.
  • Runs that failed, were cancelled after starting, or exceeded the time limit are charged for the time actually used.
  • A run in progress is not charged yet; its amount appears when it finishes.
Run durationBilled minutes
1 second1
59 seconds1
70 seconds2
60 minutes60

Current cycle cost

The Current cycle cost card adds the stored amounts of the runs completed in the cycle, also showing how many runs there were and how many minutes were accounted. Each run is added to the cost once its amount is recorded, a few moments after it finishes, even before payment processing. That amount does not change if the plan price changes later.

The Resets on line shows the next billing date; when there is no next date set, it is not shown. On that date, the run list, cycle cost, logs, and metrics shown start over, independently of financial settlement. Each run belongs to the cycle where it started, even if it finishes after the change.

Run, log, and metric records are kept internally for up to 90 days. Materialized usage and financial records are kept for audit and are not deleted when the displayed cycle starts over.

At the cycle charge, the amounts are added up and taken first from the organization balance; anything left is charged to the card in whole cents, and the remaining fraction of a cent carries over to the next cycle. Learn more in Payments and billing.

Storage

The temporary disk, with the size included in the plan, is created for each run and adds no charge, but its data is not kept for the next run. With Keep data between runs turned on, files in the Persistent directory are kept, and persistent storage is billed separately, by GB-hour, while the project exists — including when paused — until deletion.

Quick troubleshooting

What you seeWhat to do
FailedOpen View logs, look for the error message, and confirm the image runs the expected command.
Out of memory: the run reached the memory limit of the plan.Move to a plan with more memory in the Job plan card.
Out of disk: the run wrote more than the temporary storage of the plan.Delete temporary files as soon as you no longer need them, or move to a plan with more storage in the Job plan card.
Time limit exceededThe task did not finish within 60 minutes. Check that the image is a routine that finishes on its own (not a server) or split the work into smaller parts.
Metrics unavailableThe run was too short to have samples; this does not mean zero usage.
No new runsCheck the cron expression in UTC under Next execution times, whether the project is paused, and whether another run is in progress — skipped times are not queued.
Deleting asks you to waitRuns are still being finalized; wait a moment and try again.

Next steps

Last updated on

On this page