Schedules · Ephemeral docs

Start a saved workflow on a timetable. Every key can list and read schedules and start one now; creating, changing and deleting them needs an owner or admin. See schedules for how starts work.

Create a schedule

POST/v1/schedules

Checks that the workflow resolves into a run that would be admitted now, then saves the schedule. Responds 201 with the schedule.

Body

workflowstringrequired

Name of the saved workflow to start.

cronstringrequired

Five-field cron expression, or a shorthand such as @daily or @every 90m. At most once a minute.

timezonestring

IANA time zone the timetable is read in, such as Europe/Madrid. Default UTC.

namestring

A label for people. Up to 128 characters.

inputany JSON

Input for every run. Up to 1 MiB.

max_cost_microsinteger

Budget for every run. The default budget when omitted.

skip_if_runningboolean

Skip a start while the previous run is still going. Default true.

enabledboolean

Default true.

curl -X POST $EPHEMERAL_URL/v1/schedules \
  -H "Authorization: Bearer $EPHEMERAL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow": "welcome-new-customers",
    "name": "Weekday welcome emails",
    "cron": "0 9 * * 1-5",
    "timezone": "Asia/Tokyo",
    "input": { "signed_up": "yesterday" },
    "max_cost_micros": 200000
  }'

Schedule fields set by Ephemeral

next_run_atstring | null

The next start, in UTC. null while the schedule is off.

last_run_atstring

When the schedule last came due.

last_run_idstring

The run it last started.

last_errorstring

Why the last start was skipped or failed, or why the schedule paused. Empty after a good start.

failuresinteger

Failed starts in a row. At 5 the schedule turns itself off.

Preview a timetable

POST/v1/schedules/preview

Checks cron and timezone and returns the next five start times, without saving anything. An invalid timetable returns 400 with the reason.

JSON

{ "next": ["2026-10-05T00:00:00Z", "2026-10-06T00:00:00Z", "2026-10-07T00:00:00Z", "2026-10-08T00:00:00Z", "2026-10-09T00:00:00Z"] }

List schedules

GET/v1/schedules

Returns {"items": [...]}, oldest first. Add ?workflow= to list one workflow's schedules.

Get a schedule

GET/v1/schedules/{id}

Update a schedule

PATCH/v1/schedules/{id}

Send any of the create fields; the rest stay as they are. A new cron or timezone counts the next start from now. Setting enabled to true on a paused schedule clears its failures.

Start now

POST/v1/schedules/{id}/run

Starts the workflow now with the schedule's input and budget, outside the timetable. Responds 202 with the run, which carries the schedule's ID.

Delete a schedule

DELETE/v1/schedules/{id}

Responds 204. Runs it started keep their record.

Runs of a schedule

GET /v1/runs?schedule={id} lists the runs a schedule started, newest first, with the same paging as listing runs.

An organization can have up to 50 schedules.