Schedules

A schedule creates jobs on a cron expression or a fixed interval. Schedules are evaluated by the server, so they survive worker restarts.

API referenceBase URL https://api.sextant.example/v25 endpoints

The Schedule object

idstring

Unique id, prefixed sch_.

namestring

Unique, human-readable name.

cronstring

Five-field cron expression.

timezonestring

IANA time zone the expression is evaluated in.

overlapstring

skip, queue or allow.

pausedboolean

Paused schedules create no jobs.

next_run_atstring

Next planned run, UTC.

Create a schedule

POST/schedules

Creates a schedule. Either cron or every is required. every accepts durations such as 15m or 6h.

Required scope schedules:write

Request body

namestring required

Unique name.

cronstring optional

Five-field cron expression.

everystring optional

Fixed interval, for example 15m.

timezonestring optional default "UTC"

IANA time zone.

queuestring required

Queue for the created jobs.

handlerstring required

Handler name.

payloadobject optional default {}

Payload for each job.

overlapstring optional default "skip"

What to do if the previous run is still going.

Request

cURLShell

curl -X POST https://api.sextant.example/v2/schedules \
  -H "Authorization: Bearer $SEXTANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"name":"nightly-report","cron":"0 2 * * *","timezone":"Europe/Paris","queue":"reports","handler":"build-report","payload":{"range":"24h"}}'

NodeTypeScript

const result = await sextant.schedules.create({
  name: 'nightly-report',
  cron: '0 2 * * *',
  timezone: 'Europe/Paris',
  queue: 'reports',
  handler: 'build-report',
  payload: {
    range: '24h',
  },
});

PythonPython

result = client.schedules.create(
    name="nightly-report",
    cron="0 2 * * *",
    timezone="Europe/Paris",
    queue="reports",
    handler="build-report",
    payload={
        "range": "24h",
    },
)

GoGo

result, err := client.Schedules.Create(ctx, &sextant.ScheduleCreateParams{
	Name: "nightly-report",
	Cron: "0 2 * * *",
	Timezone: "Europe/Paris",
	Queue: "reports",
	Handler: "build-report",
	Payload: map[string]any{
		"range": "24h",
	},
})
if err != nil {
	return err
}

Responses

The schedule was created.

201JSON

{
  "id": "sch_2b7d1c",
  "name": "nightly-report",
  "cron": "0 2 * * *",
  "timezone": "Europe/Paris",
  "queue": "reports",
  "handler": "build-report",
  "payload": {
    "range": "24h"
  },
  "paused": false,
  "overlap": "skip",
  "next_run_at": "2026-10-21T00:00:00Z",
  "last_run_at": "2026-10-20T00:00:01Z",
  "created_at": "2026-09-02T14:20:00Z"
}

List schedules

GET/schedules

Returns every schedule, ordered by name.

Required scope schedules:read

Query parameters

pausedboolean optional

Only paused or only active schedules.

limitinteger optional default 50

Page size, 1 to 200.

cursorstring optional

Pagination cursor.

Request

cURLShell

curl https://api.sextant.example/v2/schedules?limit=20 \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.schedules.list({
  limit: 20,
});

PythonPython

result = client.schedules.list(limit=20)

GoGo

result, err := client.Schedules.List(ctx, &sextant.ListParams{Limit: 20})
if err != nil {
	return err
}

Responses

A page of schedules.

200JSON

{
  "data": [
    {
      "id": "sch_2b7d1c",
      "name": "nightly-report",
      "cron": "0 2 * * *",
      "timezone": "Europe/Paris",
      "queue": "reports",
      "handler": "build-report",
      "payload": {
        "range": "24h"
      },
      "paused": false,
      "overlap": "skip",
      "next_run_at": "2026-10-21T00:00:00Z",
      "last_run_at": "2026-10-20T00:00:01Z",
      "created_at": "2026-09-02T14:20:00Z"
    }
  ],
  "next_cursor": "cur_Xk92"
}

Retrieve a schedule

GET/schedules/{schedule_id}

Returns one schedule with its next planned run.

Required scope schedules:read

Path parameters

schedule_idstring required

The schedule id or name.

Request

cURLShell

curl https://api.sextant.example/v2/schedules/sch_2b7d1c \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

const result = await sextant.schedules.get('sch_2b7d1c');

PythonPython

result = client.schedules.get("sch_2b7d1c")

GoGo

result, err := client.Schedules.Get(ctx, "sch_2b7d1c")
if err != nil {
	return err
}

Responses

The schedule.

200JSON

{
  "id": "sch_2b7d1c",
  "name": "nightly-report",
  "cron": "0 2 * * *",
  "timezone": "Europe/Paris",
  "queue": "reports",
  "handler": "build-report",
  "payload": {
    "range": "24h"
  },
  "paused": false,
  "overlap": "skip",
  "next_run_at": "2026-10-21T00:00:00Z",
  "last_run_at": "2026-10-20T00:00:01Z",
  "created_at": "2026-09-02T14:20:00Z"
}

Update a schedule

PATCH/schedules/{schedule_id}

Changes any field, including paused. A change to cron or timezone recomputes next_run_at immediately.

Required scope schedules:write

Path parameters

schedule_idstring required

The schedule id or name.

Request body

cronstring optional

New cron expression.

timezonestring optional

New time zone.

pausedboolean optional

Pause or resume.

payloadobject optional

Replaces the payload.

Request

cURLShell

curl -X PATCH https://api.sextant.example/v2/schedules/sch_2b7d1c \
  -H "Authorization: Bearer $SEXTANT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"paused":true}'

NodeTypeScript

const result = await sextant.schedules.update('sch_2b7d1c', {
  paused: true,
});

PythonPython

result = client.schedules.update(
    "sch_2b7d1c",
    paused=True,
)

GoGo

result, err := client.Schedules.Update(ctx, "sch_2b7d1c", &sextant.ScheduleUpdateParams{
	Paused: true,
})
if err != nil {
	return err
}

Responses

The updated schedule.

200JSON

{
  "id": "sch_2b7d1c",
  "name": "nightly-report",
  "cron": "0 2 * * *",
  "timezone": "Europe/Paris",
  "queue": "reports",
  "handler": "build-report",
  "payload": {
    "range": "24h"
  },
  "paused": true,
  "overlap": "skip",
  "next_run_at": "2026-10-21T00:00:00Z",
  "last_run_at": "2026-10-20T00:00:01Z",
  "created_at": "2026-09-02T14:20:00Z"
}

Delete a schedule

DELETE/schedules/{schedule_id}

Deletes the schedule. Jobs it already created are not touched.

Required scope schedules:write

Path parameters

schedule_idstring required

The schedule id or name.

Request

cURLShell

curl -X DELETE https://api.sextant.example/v2/schedules/sch_2b7d1c \
  -H "Authorization: Bearer $SEXTANT_TOKEN"

NodeTypeScript

await sextant.schedules.delete('sch_2b7d1c');

PythonPython

client.schedules.delete("sch_2b7d1c")

GoGo

if err := client.Schedules.Delete(ctx, "sch_2b7d1c"); err != nil {
	return err
}

Responses

Deleted. No body.

No response body.