Skip to main content
The SchedulesResource on the Figranium JavaScript SDK lets you automate when tasks run. You can list every scheduled task, attach a recurring schedule to a specific task, delete it, validate a schedule before applying it, and inspect the overall scheduler health. All schedule payloads use the shared Schedule type, which supports interval, hourly, daily, weekly, monthly, and raw cron expressions.

​
Schedule type

A Schedule object controls whether and how often a task runs automatically.
  • enabled : whether the schedule is active.
  • frequency : the recurrence pattern. Use "interval" for a simple minute-based timer, "hourly" / "daily" / "weekly" / "monthly" for calendar-based runs, or omit it and supply cron directly.
  • intervalMinutes : required when frequency is "interval".
  • hour and minute : used with "daily", "weekly", and "monthly" to set the time of day.
  • daysOfWeek : array of weekday numbers (0 = Sunday) for "weekly".
  • dayOfMonth : day number (1 to 31) for "monthly".
  • cron : a raw cron string when you need full control.

​
Examples

Run a task every 15 minutes:
interval-schedule.ts
Run a task every Monday and Wednesday at 09:30:
weekly-schedule.ts

​
Methods

Retrieve all tasks that currently have a schedule configured.
  • HTTP endpoint: GET /api/schedules
  • Signature: schedules.list(options?: RequestOptions): Promise<{ schedules: ScheduleEntry[] }>
list-schedules.ts
Returns an object with a schedules array. Each ScheduleEntry contains taskId, taskName, mode, and the attached Schedule object.
Attach or update a schedule for a specific task.
  • HTTP endpoint: POST /api/schedules/:taskId
  • Signature: schedules.set(taskId: string, schedule: Schedule, options?: RequestOptions): Promise<{ schedule: Schedule; description: string | null; nextRun: number | null }>
set-schedule.ts
Returns an object containing the saved schedule, a human-readable description, and the nextRun timestamp (or null if the schedule is disabled or invalid).
Remove a task’s schedule entirely.
  • HTTP endpoint: DELETE /api/schedules/:taskId
  • Signature: schedules.delete(taskId: string, options?: RequestOptions): Promise<{ success: boolean }>
delete-schedule.ts
Returns { success: boolean } indicating whether the schedule was removed.
Inspect the current schedule for a single task, including its computed cron expression and validity.
  • HTTP endpoint: GET /api/schedules/:taskId/status
  • Signature: schedules.status(taskId: string, options?: RequestOptions): Promise<{ schedule: Schedule; cron: string | null; description: string | null; isValid: boolean }>
schedule-status.ts
Returns an object with the current schedule, the resolved cron string, a human-readable description, and an isValid flag.
Validate a schedule payload for a task without saving it. This is useful for previewing the next run time and confirming a cron expression before you call set.
  • HTTP endpoint: POST /api/schedules/:taskId/describe
  • Signature: schedules.describe(taskId: string, schedule: Schedule, options?: RequestOptions): Promise<{ valid: boolean; description: string | null; cron: string | null; nextRun: number | null }>
describe-schedule.ts
Returns an object with valid, description, cron, and nextRun. If valid is false, the schedule will not be accepted by set.
Get a high-level view of the scheduler state across all tasks.
  • HTTP endpoint: GET /api/schedules/status/all
  • Signature: schedules.overallStatus(options?: RequestOptions): Promise<UnknownRecord>
overall-status.ts
Returns an UnknownRecord (a plain object with Record<string, unknown> shape). The exact fields depend on the server version; inspect the response to discover available keys.

​
Error handling

Schedule methods throw FigraniumError on failure. Common cases include a missing task ID (404) or an invalid schedule payload (400). See Error handling for retry guidance and error codes.

Tasks

Create and manage the tasks you schedule.

Executions

Inspect the runs produced by scheduled tasks.

Request options

Pass signal, timeoutMs, and custom headers.

Errors

Handle FigraniumError responses.