About the scheduler

With the scheduler, you set up work to happen at set times or regular intervals. Each piece of work is a job. Typical jobs send a report email every morning, refresh cached data every 10 minutes, or update summary figures once an hour.

A job belongs to a project. It holds a schedule in a time zone, and a target: the HTTPS address to call, with the method, headers, and body to send. At each time on the schedule, we call the target, and your app does the work.

Jobs, runs, and attempts

• A run is one occurrence of the schedule, or one Run now.
• An attempt is one call to the target within a run.
• A run succeeds when your target answers with a 2xx status. Otherwise the attempt fails, and the run is retried if the job allows it.

At least once

The scheduler is built to run every job at least once for each time on its schedule. In rare cases, such as a network failure after your target has done the work but before we see its answer, the same run reaches your target more than once.

Make your target safe to call twice for the same run. See Repeated calls.

One run at a time

A job never has two runs at once. If a run is still going, retries included, when the next time on the schedule comes, the next run waits until it finishes.

If runs are missed, only the latest one happens. See Missed runs.

Retries

When a run fails, it is tried again with a wait that grows each time, following the job’s retry policy. By default, a failed run is not retried. See Retry jobs.

Repeated calls

Every call carries headers that identify it. X-Scheduler-JobId names the job, and X-Scheduler-ScheduleTime holds the time the run was due. The schedule time stays the same across every attempt of a run.

Together, the two identify a run. Record them when your target handles a call, and if the same pair comes again, answer with a 2xx status and do nothing. See Request headers.

Targets we call

We call HTTPS addresses on the public internet. Addresses on private networks, and names that resolve to them, are never called, and the attempt fails with the class blocked.

Ways to manage jobs

Create and change jobs through the REST API. In the console, you can see a project’s jobs and every run, run a job now, turn it off and on, and delete it.