API reference

Schedules

Cron expressions with time zones that create a job every time they fire.

A schedule creates a job on a cron expression, in the time zone you choose, so 0 2 * * * in Europe/Amsterdam means 2 AM local time all year, across daylight saving changes.

Each firing creates an ordinary job with the schedule's queue, task and payload. The job's schedule field points back here.

Endpoints: 5
ID prefix: sch_
Attributes: 15

The schedule object

Every schedule endpoint returns this object, or a list of them. Attributes marked null are always present in the response, so you can rely on the shape.

Attributes

idstring

Unique identifier, prefixed with sch_.

objectstring

Always schedule.

namestring

Unique name within your project.

cronstring

Five-field cron expression, such as 0 2 * * *.

timezonestring

IANA time zone the expression is read in.

queuestring

Queue each job is created on.

taskstring

Task each job runs.

payloadobject

Payload copied into each job.

statusenum

active or paused.

overlapenum

What happens when the previous job is still running: skip, queue or allow.

next_run_attimestamp | null

Next firing in UTC, or null while paused.

last_run_attimestamp | null

Most recent firing in UTC.

last_jobstring | null

ID of the job created by the most recent firing.

created_attimestamp

When the object was created, in ISO 8601 UTC.

livemodeboolean

true for objects created with a live key, false for the test sandbox.

The schedule object

{  "id": "sch_2Mf6Xb8Qn4",  "object": "schedule",  "name": "nightly-report",  "cron": "0 2 * * *",  "timezone": "Europe/Amsterdam",  "queue": "reports",  "task": "build-daily-report",  "payload": {    "format": "pdf"  },  "status": "active",  "overlap": "skip",  "next_run_at": "2026-10-15T00:00:00Z",  "last_run_at": "2026-10-14T00:00:00Z",  "last_job": "job_8Vx1Lk5Pq3",  "created_at": "2026-09-02T14:20:11Z",  "livemode": false}

Create a schedule

POST/v3/schedules

Creates a schedule that starts firing at its next matching time.

Body parameters

namestringrequired

Unique name, such as nightly-report.

cronstringrequired

Five-field cron expression. The shortest interval is one minute.

queuestringrequired

Queue for the created jobs.

taskstringrequired

Task for the created jobs.

timezonestringdefault: UTC

IANA time zone, such as America/Chicago.

payloadobjectdefault: {}

Copied into every job.

overlapenumdefault: skip

skip, queue or allow.

Returns

The new schedule object with next_run_at filled in.

POST /v3/schedules

curl https://api.halyard.example/v3/schedules \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -H "Content-Type: application/json" \  -d '{    "name": "nightly-report",    "cron": "0 2 * * *",    "timezone": "Europe/Amsterdam",    "queue": "reports",    "task": "build-daily-report",    "payload": {      "format": "pdf"    }  }'

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const schedule = await halyard.schedules.create({  name: "nightly-report",  cron: "0 2 * * *",  timezone: "Europe/Amsterdam",  queue: "reports",  task: "build-daily-report",  payload: { format: "pdf" },});

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) schedule = halyard.schedules.create(    name="nightly-report",    cron="0 2 * * *",    timezone="Europe/Amsterdam",    queue="reports",    task="build-daily-report",    payload={"format": "pdf"},)

Response201 Created

{  "id": "sch_2Mf6Xb8Qn4",  "object": "schedule",  "name": "nightly-report",  "cron": "0 2 * * *",  "timezone": "Europe/Amsterdam",  "queue": "reports",  "task": "build-daily-report",  "payload": {    "format": "pdf"  },  "status": "active",  "overlap": "skip",  "next_run_at": "2026-10-15T00:00:00Z",  "last_run_at": null,  "last_job": null,  "created_at": "2026-10-14T10:05:22Z",  "livemode": false}

Update a schedule

PATCH/v3/schedules/{id}

Changes a schedule. Only the fields you send are updated, and next_run_at is recalculated right away.

Path parameters

idstringrequired

The schedule's ID.

Body parameters

cronstring

New cron expression.

timezonestring

New IANA time zone.

payloadobject

Replaces the payload for future jobs.

overlapenum

skip, queue or allow.

statusenum

active or paused. Same as the pause endpoint.

Returns

The updated schedule object.

PATCH /v3/schedules/{id}

curl -X PATCH https://api.halyard.example/v3/schedules/sch_2Mf6Xb8Qn4 \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -H "Content-Type: application/json" \  -d '{    "cron": "30 6 * * 1-5"  }'

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const schedule = await halyard.schedules.update("sch_2Mf6Xb8Qn4", {  cron: "30 6 * * 1-5",});

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) schedule = halyard.schedules.update(    "sch_2Mf6Xb8Qn4",    cron="30 6 * * 1-5",)

Response200 OK

{  "id": "sch_2Mf6Xb8Qn4",  "object": "schedule",  "name": "nightly-report",  "cron": "30 6 * * 1-5",  "timezone": "Europe/Amsterdam",  "queue": "reports",  "task": "build-daily-report",  "payload": {    "format": "pdf"  },  "status": "active",  "overlap": "skip",  "next_run_at": "2026-10-15T04:30:00Z",  "last_run_at": "2026-10-14T00:00:00Z",  "last_job": "job_8Vx1Lk5Pq3",  "created_at": "2026-09-02T14:20:11Z",  "livemode": false}

Pause a schedule

POST/v3/schedules/{id}/pause

Stops a schedule from firing. Jobs it already created are not affected. Missed firings are not caught up when you resume.

Path parameters

idstringrequired

The schedule's ID.

Returns

The schedule object with status set to paused.

POST /v3/schedules/{id}/pause

curl -X POST https://api.halyard.example/v3/schedules/sch_2Mf6Xb8Qn4/pause \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const schedule = await halyard.schedules.pause("sch_2Mf6Xb8Qn4");

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) schedule = halyard.schedules.pause("sch_2Mf6Xb8Qn4")

Response200 OK

{  "id": "sch_2Mf6Xb8Qn4",  "object": "schedule",  "name": "nightly-report",  "cron": "0 2 * * *",  "timezone": "Europe/Amsterdam",  "queue": "reports",  "task": "build-daily-report",  "payload": {    "format": "pdf"  },  "status": "paused",  "overlap": "skip",  "next_run_at": null,  "last_run_at": "2026-10-14T00:00:00Z",  "last_job": "job_8Vx1Lk5Pq3",  "created_at": "2026-09-02T14:20:11Z",  "livemode": false}

Delete a schedule

DELETE/v3/schedules/{id}

Deletes a schedule permanently. Jobs it created keep running and keep their schedule ID for reference.

Path parameters

idstringrequired

The schedule's ID.

Returns

An object with the schedule's id and deleted: true.

DELETE /v3/schedules/{id}

curl -X DELETE https://api.halyard.example/v3/schedules/sch_2Mf6Xb8Qn4 \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d"

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const deleted = await halyard.schedules.delete("sch_2Mf6Xb8Qn4");

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) deleted = halyard.schedules.delete("sch_2Mf6Xb8Qn4")

Response200 OK

{  "id": "sch_2Mf6Xb8Qn4",  "object": "schedule",  "deleted": true}

List schedules

GET/v3/schedules

Lists schedules, sorted by next_run_at so the next one to fire comes first.

Query parameters

statusenum

Only active or only paused schedules.

limitintegerdefault: 20

How many objects to return, between 1 and 100.

starting_afterstring

A cursor: the ID of the last object on the previous page. The next page starts right after it.

ending_beforestring

A cursor for paging backwards: the ID of the first object on the current page.

Returns

A list object with schedule objects in data.

GET /v3/schedules

curl -G https://api.halyard.example/v3/schedules \  -H "Authorization: Bearer hy_test_51Hq8Zx2rTmV9cKpL3d" \  -d status=active \  -d limit=2

import { Halyard } from "@halyard/node"; const halyard = new Halyard(process.env.HALYARD_KEY); const schedules = await halyard.schedules.list({  status: "active",  limit: 2,});

import osfrom halyard import Halyard halyard = Halyard(os.environ["HALYARD_KEY"]) schedules = halyard.schedules.list(status="active", limit=2)

Response200 OK

{  "object": "list",  "url": "/v3/schedules",  "has_more": false,  "data": [    {      "id": "sch_6Kd1Wq9Lr2",      "object": "schedule",      "name": "expire-trials",      "cron": "*/15 * * * *",      "timezone": "UTC",      "queue": "billing",      "task": "expire-trials",      "payload": {},      "status": "active",      "overlap": "skip",      "next_run_at": "2026-10-14T09:45:00Z",      "last_run_at": "2026-10-14T09:30:00Z",      "last_job": "job_5Yc7Gm3Ka1",      "created_at": "2026-09-02T14:20:11Z",      "livemode": false    },    {      "id": "sch_2Mf6Xb8Qn4",      "object": "schedule",      "name": "nightly-report",      "cron": "0 2 * * *",      "timezone": "Europe/Amsterdam",      "queue": "reports",      "task": "build-daily-report",      "payload": {        "format": "pdf"      },      "status": "active",      "overlap": "skip",      "next_run_at": "2026-10-15T00:00:00Z",      "last_run_at": "2026-10-14T00:00:00Z",      "last_job": "job_8Vx1Lk5Pq3",      "created_at": "2026-09-02T14:20:11Z",      "livemode": false    }  ]}

Overview

The schedule object

Create a schedule

Update a schedule

Pause a schedule

Delete a schedule

List schedules