Preview a schedule
POST/
Shows when a schedule trigger would run: its cron and its next 5 times.
Needs any API token. No permission is checked.
Parameters
Body
Optional. Left out, it previews the schedule’s defaults: every hour, weekdays only. So does a body with the settings at the top level: put them under config.
configOptional · objectThe schedule trigger’s
config. For the fields eachfrequencytakes, see Get a trigger’s fields.
Check for error first
An unknown frequency or a bad cron comes back as {"cron": "", "timezone": "", "error": "unknown frequency: …"}, with no nextRuns. An unknown time zone keeps its cron and timezone beside error.
run_on_weekends is false by default, so every_day skips Saturday and Sunday unless you set it. The preview uses the scheduler’s own code, so it matches what will run. See Run on a schedule.
Responses
- 200OK
The cron and the next 5 times, in the schedule’s own time zone. A schedule that can never run answers 200 too, with
errorinstead. The body isn’t JSON, or
configisn’t an object.- 403
FORBIDDENThe token may not do this.
- 404
NOT_FOUNDThe workers have no schedule app.
The worker failed. Try again.
No worker is checked in.
Any call can also answer: 401 UNAUTHORIZED · 401 TOKEN_ENDED · 403 TOKEN_SURFACE_OFF · 403 FEATURE_OFF · 403 EMBED_NOT_ALLOWED · 403 EMBED_NOT_AVAILABLE · 403 ACCOUNT_SUSPENDED · 413 PAYLOAD_TOO_LARGE · 415 INVALID_CONTENT_TYPE · 429 RATE_LIMITED · 503 BUSY · 503 PAUSED · 503 SERVICE_UNAVAILABLE. See Errors.
Request
GORUNNER="https://api.gorunner.io"
GORUNNER_TOKEN="grt_…" # needs any API token
curl -X POST "$GORUNNER/api/pieces/schedule/next-runs" \
-H "Authorization: Bearer $GORUNNER_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"config": {
"frequency": "every_day",
"hour_of_the_day": "9",
"timezone": "Europe/Berlin",
"run_on_weekends": true
}
}'const GORUNNER = "https://api.gorunner.io";
const TOKEN = process.env.GORUNNER_TOKEN;
const res = await fetch(
`${GORUNNER}/api/pieces/schedule/next-runs`,
{
method: "POST",
headers: {
Authorization: `Bearer ${TOKEN}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
config: {
frequency: "every_day",
hour_of_the_day: "9",
timezone: "Europe/Berlin",
run_on_weekends: true,
},
}),
},
);
const { data } = await res.json();import os, requests
GORUNNER = "https://api.gorunner.io"
TOKEN = os.environ["GORUNNER_TOKEN"]
res = requests.post(
f"{GORUNNER}/api/pieces/schedule/next-runs",
headers={"Authorization": f"Bearer {TOKEN}"},
json={
"config": {
"frequency": "every_day",
"hour_of_the_day": "9",
"timezone": "Europe/Berlin",
"run_on_weekends": True,
},
},
)
data = res.json()["data"]Response · 200 OK
{
"data": {
"cron": "0 9 * * *",
"timezone": "Europe/Berlin",
"nextRuns": [
"2026-10-26T09:00:00+01:00",
"2026-10-27T09:00:00+01:00",
"2026-10-28T09:00:00+01:00",
"2026-10-29T09:00:00+01:00",
"2026-10-30T09:00:00+01:00"
]
}
}Every field
{"config": {…}}, with the schedule trigger’s config under config, exactly as it would sit in the definition. Get its legal fields from GET /api/pieces/schedule/triggers/schedule?frequency=<value>.
Body
configOptional · objectThe schedule trigger’s
config, e.g.{"frequency":"every_day","hour_of_the_day":9,"timezone":"UTC","run_on_weekends":true}. Absent previews the app’s defaults. Legal fields per frequency come from GET /api/pieces/schedule/triggers/schedule?frequency=<value>.
Response · 200 OK
dataobjectThe compiled schedule. Either
nextRunsorerroris present, never both.cronstringThe cron expression this configuration compiles to. Empty when the frequency or the cron is unusable.
timezonestringThe zone the fire times are computed in. Empty when the frequency or the cron is unusable; an unknown zone is answered as sent, beside
error.nextRunsarray of timesThe next 5 fire times, RFC 3339 in the schedule’s own zone (
2026-10-31T09:00:00+01:00;Zfor UTC). Absent whenerroris set. The count is fixed and cannot be requested.errorstringWhy this schedule can never fire — an invalid cron, an unknown frequency, an unknown time zone. Carried in a 200 body, not an HTTP error.