Jobs

The job object

{
  "name": "Nightly report",
  "description": "",
  "schedule": "0 2 * * *",
  "timeZone": "Africa/Dar_es_Salaam",
  "target": {
    "url": "https://mail.example.com/tasks/report",
    "method": "POST",
    "headers": { "Content-Type": "application/json" },
    "body": "{\"full\":true}"
  },
  "signing": { "enabled": true, "audience": "" },
  "retry": {
    "count": 3,
    "maxDurationSeconds": 0,
    "minBackoffSeconds": 5,
    "maxBackoffSeconds": 3600,
    "maxDoublings": 5
  },
  "attemptDeadlineSeconds": 180
}

Fields you send

namestringRequired

1 to 100 characters, on one line. Unique in the project, ignoring case.

descriptionstring

At most 500 characters. Line breaks are allowed.

schedulestringRequired

A 5-field cron schedule, or a shortcut such as @daily. See Schedules and time zones.

timeZonestring

An IANA time zone, such as Africa/Dar_es_Salaam. UTC when empty.

target.urlstringRequired

An https URL of at most 2,048 characters, without a user name, password, or # part.

target.methodstring

GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS. POST when empty.

target.headersobject

At most 50 headers, each set once whatever its case. You cannot set Host, Content-Length, Transfer-Encoding, Connection, User-Agent, or any X-Scheduler- header, nor Authorization when signing is on.

target.bodystring

At most 100 KB, and only for POST, PUT, and PATCH.

signing.enabledboolean

Sign every call. See Verify signed calls.

signing.audiencestring

The token’s aud. The target URL without its query when empty. A custom audience must use the same scheme and host as the target URL.

retryobject

The retry policy. See Retries.

attemptDeadlineSecondsinteger

How long to wait for an answer, 15 to 1,800 seconds. 180 when you leave it out.

Fields we add

idstring

The job’s ID.

projectIdstring

The project the job belongs to.

statestring

enabled or paused.

nextRunAtstring or null

When the job runs next. null while it is paused.

lastRunAtstring or null

When the job last ran.

signing.effectiveAudiencestring

The audience its tokens carry, after the default is applied.

createdAtstring

When the job was created.

updatedAtstring

When the job was last changed.

List jobs

Returns the project’s jobs, newest first, a page at a time. See Paging.

Create a job

Send the job’s fields. Returns 201 with the new job. A name already used in the project gets 409 with the code job_name_taken.

Read a job

Replace a job

Send every field, as for creating it. Fields you leave out go back to their defaults. The next run time is worked out again from the new schedule.

Delete a job

Deletes the job and all its runs. Returns 204. This cannot be undone.

Pause and resume

Both return the job. A paused job is not scheduled, and pausing cancels any scheduled run that is waiting to start or to retry. Resuming schedules the job again from now, so occurrences missed while it was paused do not run.

Run now

Starts a run straight away, whatever the schedule, and returns 201 with the run. Its trigger is manual. A job that already has a run in progress gets 409 with the code run_in_progress.