Schedules API

A schedule makes a GET request to a path on your project on a cron timer. The run is an ordinary request to the project's own address, so it wakes the project and appears in its logs like any visitor's. For writing the handler, see Schedules.

GET/projects/{name}/schedulesA project's schedules, with the next run

POST/projects/{name}/schedulesAdd a schedule

PATCH/projects/{name}/schedules/{id}Pause or resume a schedule

DELETE/projects/{name}/schedules/{id}Remove a schedule

GET/schedulesEvery schedule across your projects

Cron syntax

Five fields, in UTC: minute, hour, day of month, month, day of week. Each field takes *, a number, a list a,b, a range a-b, or a step */n or a-b/n. Sunday is 0 or 7.

0 3 * * *          every day at 03:00 UTC
*/15 9-17 * * 1-5  every 15 minutes, 09:00–17:45 UTC, Monday to Friday
0 0 1 * *          midnight UTC on the first of each month

Shorthands such as @daily, names such as MON or JAN, and L and # are not accepted. A spec that does not parse is refused when you save it.

Runs that were missed while the platform was down are not replayed afterwards. A run that takes longer than 5 minutes is abandoned.

The schedule object

idstring

The schedule's id, 48 hex characters.

projectstring

The project's name.

account_idstring

The account that created it.

namestring

Your label for it.

specstring

The cron spec.

pathstring

The path requested, starting with /.

enabledboolean

false while paused.

created_atinteger

Unix seconds.

last_run_atinteger | null

When it last ran.

last_statusinteger | null

The HTTP status the last run got.

last_msinteger | null

How long the last run took, in milliseconds.

last_errorstring | null

Why the last run failed: the project answered {code} for a status outside 200–399, the job did not finish within five minutes, or the connection error. null after a run that succeeded.

next_run_atinteger | null

When it runs next, Unix seconds. null while paused. Returned by the list routes only.

List a project's schedules

GET/projects/{name}/schedulesA project's schedules, with the next run

namestringRequired

Path parameter. The project's name.

Terminal

curl https://api.fortly.com/projects/my-app-ada/schedules \
  -H "Authorization: Bearer $FORTLY_TOKEN"

JavaScript

const res = await fetch("https://api.fortly.com/projects/my-app-ada/schedules", {
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});
const { schedules } = await res.json();

JSON

{
  "schedules": [
    {
      "id": "5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d",
      "project": "my-app-ada",
      "account_id": "8b1e4f0c2d6a4e7f9c3b5a1d0e2f4c6b",
      "name": "Nightly digest",
      "spec": "0 3 * * *",
      "path": "/jobs/digest",
      "enabled": true,
      "created_at": 1791820800,
      "last_run_at": 1791860401,
      "last_status": 200,
      "last_ms": 412,
      "last_error": null,
      "next_run_at": 1791946800
    }
  ]
}

Add a schedule

POST/projects/{name}/schedulesAdd a schedule

Adds a schedule, enabled.

In the path, {name} is the project's name. The JSON body takes:

namestringRequired

A label for the schedule. Not empty.

specstringRequired

A five-field cron spec, in UTC.

pathstringRequired

The path to request on your project, starting with /. May include a query string.

Terminal

curl -X POST https://api.fortly.com/projects/my-app-ada/schedules \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"Nightly digest","spec":"0 3 * * *","path":"/jobs/digest"}'

JavaScript

const res = await fetch("https://api.fortly.com/projects/my-app-ada/schedules", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ name: "Nightly digest", spec: "0 3 * * *", path: "/jobs/digest" }),
});
const schedule = await res.json();

Answers 201 with the schedule, without next_run_at:

JSON

{
  "id": "5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d",
  "project": "my-app-ada",
  "account_id": "8b1e4f0c2d6a4e7f9c3b5a1d0e2f4c6b",
  "name": "Nightly digest",
  "spec": "0 3 * * *",
  "path": "/jobs/digest",
  "enabled": true,
  "created_at": 1791820800,
  "last_run_at": null,
  "last_status": null,
  "last_ms": null,
  "last_error": null
}

An empty name, a spec that does not parse, or a path without a leading / answers 400 with the reason.

Pause or resume a schedule

PATCH/projects/{name}/schedules/{id}Pause or resume a schedule

namestringRequired

Path parameter. The project's name.

idstringRequired

Path parameter. The schedule's id.

enabledbooleanRequired

Body. false to pause, true to resume.

Terminal

curl -X PATCH https://api.fortly.com/projects/my-app-ada/schedules/5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d \
  -H "Authorization: Bearer $FORTLY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"enabled":false}'

JavaScript

const id = "5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d";
await fetch(`https://api.fortly.com/projects/my-app-ada/schedules/${id}`, {
  method: "PATCH",
  headers: {
    Authorization: `Bearer ${process.env.FORTLY_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ enabled: false }),
});

Answers 204 No Content, or 404 with no such schedule when the id is not one of this project's schedules. To change a schedule's spec or path, remove it and add a new one.

Remove a schedule

DELETE/projects/{name}/schedules/{id}Remove a schedule

namestringRequired

Path parameter. The project's name.

idstringRequired

Path parameter. The schedule's id.

Terminal

curl -X DELETE https://api.fortly.com/projects/my-app-ada/schedules/5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d \
  -H "Authorization: Bearer $FORTLY_TOKEN"

JavaScript

const id = "5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d";
await fetch(`https://api.fortly.com/projects/my-app-ada/schedules/${id}`, {
  method: "DELETE",
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});

Answers 204 No Content, or 404 with no such schedule.

List all schedules

GET/schedulesEvery schedule across your projects

Every schedule on every project you can access, in the same shape as List a project's schedules, next_run_at included.

Terminal

curl https://api.fortly.com/schedules \
  -H "Authorization: Bearer $FORTLY_TOKEN"

JavaScript

const res = await fetch("https://api.fortly.com/schedules", {
  headers: { Authorization: `Bearer ${process.env.FORTLY_TOKEN}` },
});
const { schedules } = await res.json();

JSON

{
  "schedules": [
    {
      "id": "5e0b8f1c3a7d4e2f9b6c1a8d3e5f7a9b0c2d4e6f8a1b3c5d",
      "project": "my-app-ada",
      "name": "Nightly digest",
      "spec": "0 3 * * *",
      "path": "/jobs/digest",
      "enabled": true,
      "next_run_at": 1791946800
    }
  ]
}

Items are shortened here; each is a complete schedule object.