Scheduling
Job scheduling configuration and fire time preview.
GET /api/job-fire-times
Preview upcoming execution times for a given schedule configuration.
Authentication: Required
Query Parameters:
| Parameter | Type | Required | Description |
|---|---|---|---|
interval | string | No | Recurrence expression, in the shape the intervalType expects. Omit it for Once. |
intervalType | string | No | One of Once, Minutes, Hourly, Daily, Weekly, Monthly, Yearly, Custom |
timeZone | string | No | Timezone (e.g. America/New_York); defaults to the server's guess |
startOn | date | No | Start date |
howMany | integer | No | Number of fire times to return (default: 3) |
Example:
GET /api/job-fire-times?interval=0 8 * * *&intervalType=Custom&timeZone=America/New_York&howMany=5
A Once schedule has no recurrence to describe, so it takes no interval. It returns a single fire time, or an empty array once startOn has passed:
GET /api/job-fire-times?intervalType=Once&startOn=2051-01-06T09:00:00Z
Response:
A plain array of upcoming run times (ISO 8601 strings).
[
"2026-01-15T16:20:00.000Z",
"2026-01-15T16:20:00.000Z",
"2026-01-15T16:20:00.000Z",
"… 2 more items (5 total) — omitted from docs"
]
Use this endpoint before creating or updating a job to validate that the schedule configuration produces the expected execution times.
Job Scheduling Fields
When creating or updating a job via POST /api/jobs or PUT /api/jobs/{id}, use these fields:
| Field | Type | Description |
|---|---|---|
interval | string | Recurrence expression, in the shape the intervalType expects. null for Once. |
intervalType | string | One of Once, Minutes, Hourly, Daily, Weekly, Monthly, Yearly, Custom. Values are case sensitive. |
timezone | string | Timezone for schedule interpretation (e.g., "America/New_York") |
startOn | date | Job won't run before this date. For Once, this is the single run. |
endOn | date | Job won't run after this date |
enabled | boolean | Enable/disable job execution |
interval and intervalType describe one schedule between them, so they have to
agree. Once is the only type described by startOn alone, and it must send a
null interval; every other type is meaningless without one.
Interval Shapes
Only Custom takes a free-form cron expression. The calendar types take a cron
Informer composes for them, and the two frequency types take a shorter form:
intervalType | interval shape | Example |
|---|---|---|
Once | none | null |
Minutes | the number of minutes | "30" |
Hourly | 0 and the number of hours | "0 2" |
Daily | minute hour */n * * | "0 8 */1 * *" |
Weekly | minute hour * * days | "0 7 * * MON,WED,FRI" |
Monthly | minute hour day 1/n ? * | "0 9 1 1/1 ? *" |
Custom | any cron expression | "0 17 * * 5" |
Cron Expression Format
Standard cron format: minute hour day month weekday
Examples:
| Expression | Description |
|---|---|
0 8 * * * | Daily at 8:00 AM |
0 */4 * * * | Every 4 hours |
0 9 * * 1 | Every Monday at 9:00 AM |
0 0 1 * * | First day of month at midnight |
*/15 * * * * | Every 15 minutes |
Simple Interval Format
Human-readable intervals: <number> <unit>
Examples:
| Interval | Description |
|---|---|
1 hour | Every hour |
30 minutes | Every 30 minutes |
1 day | Daily |
1 week | Weekly |
Schedule Examples
Daily Report at 8 AM Eastern
{
"interval": "0 8 * * *",
"intervalType": "Custom",
"timezone": "America/New_York",
"enabled": true
}
Every 30 Minutes
{
"interval": "30",
"intervalType": "Minutes",
"enabled": true
}
Run Once at a Specific Time
A one-time Job runs at startOn and never again. It carries no interval, and
once it has run Informer clears its nextRunAt so it is not picked up again.
{
"interval": null,
"intervalType": "Once",
"startOn": "2051-03-01T12:00:00Z",
"enabled": true
}
Weekly on Fridays
{
"interval": "0 17 * * 5",
"intervalType": "Custom",
"timezone": "America/Los_Angeles",
"enabled": true
}