SchedulesResource: Configure and Inspect Schedules

The schedules resource on the Figranium Python 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.

from figranium import Figranium
import os

client = Figranium(api_key=os.environ["FIGRANIUM_API_KEY"])

Schedule type

A Schedule object controls whether and how often a task runs automatically.

from figranium import Schedule

# Schedule is a TypedDict with these fields:
#   enabled: bool
#   frequency: "interval" | "hourly" | "daily" | "weekly" | "monthly"
#   intervalMinutes: int
#   hour: int
#   minute: int
#   daysOfWeek: list[int]
#   dayOfMonth: int
#   cron: str
#   lastRun: str | None        # read-only
#   lastRunStatus: str | None  # read-only
#   lastRunDurationMs: int     # read-only
#   nextRun: str | None        # read-only

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.
lastRun, lastRunStatus, lastRunDurationMs, nextRun : read-only fields returned by the server.

Examples

Run a task every 15 minutes:

interval_schedule.py

from figranium import Figranium, Schedule
import os

client = Figranium(api_key=os.environ["FIGRANIUM_API_KEY"])

interval_schedule: Schedule = {
    "enabled": True,
    "frequency": "interval",
    "intervalMinutes": 15,
}

result = client.schedules.set("task-123", interval_schedule)
print(result)

Run a task every Monday and Wednesday at 09:30:

weekly_schedule.py

weekly_schedule: Schedule = {
    "enabled": True,
    "frequency": "weekly",
    "hour": 9,
    "minute": 30,
    "daysOfWeek": [1, 3],
}

result = client.schedules.set("task-123", weekly_schedule)
print(result)

Run a task daily at 07:00 with a cron expression:

cron_schedule.py

cron_schedule: Schedule = {
    "enabled": True,
    "cron": "0 7 * * *",
}

result = client.schedules.set("task-123", cron_schedule)
print(result)

Methods

list

Retrieve all tasks that currently have a schedule configured.

HTTP endpoint: GET /api/schedules
Signature: schedules.list(*, options=None)

list_schedules.py

result = client.schedules.list()

for entry in result["schedules"]:
    print(entry["taskId"], entry["taskName"], entry["schedule"]["enabled"])

Returns an object with a schedules array. Each entry contains taskId, taskName, mode, and the attached Schedule object.

set

Attach or update a schedule for a specific task.

HTTP endpoint: POST /api/schedules/{taskId}
Signature: schedules.set(task_id, schedule, *, options=None)

set_schedule.py

from figranium import Schedule

result = client.schedules.set("task-123", {
    "enabled": True,
    "frequency": "daily",
    "hour": 7,
    "minute": 0,
})

print(result["nextRun"])  # timestamp of the next scheduled run

Returns an object containing the saved schedule, a human-readable description, and the nextRun timestamp (or None if the schedule is disabled or invalid).

delete

Remove a task’s schedule entirely.

HTTP endpoint: DELETE /api/schedules/{taskId}
Signature: schedules.delete(task_id, *, options=None)

delete_schedule.py

result = client.schedules.delete("task-123")
print(result["success"])

Returns {"success": bool} indicating whether the schedule was removed.

status

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(task_id, *, options=None)

schedule_status.py

status = client.schedules.status("task-123")

print(status["isValid"], status["cron"], status["description"])

Returns an object with the current schedule, the resolved cron string, a human-readable description, and an isValid flag.

describe

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(task_id, schedule, *, options=None)

describe_schedule.py

preview = client.schedules.describe("task-123", {
    "enabled": True,
    "frequency": "monthly",
    "dayOfMonth": 1,
    "hour": 6,
    "minute": 0,
})

print(preview["valid"], preview["cron"], preview["nextRun"])

Returns an object with valid, description, cron, and nextRun. If valid is False, the schedule will not be accepted by set.

overall_status

Get a high-level view of the scheduler state across all tasks.

HTTP endpoint: GET /api/schedules/status/all
Signature: schedules.overall_status(*, options=None)

overall_status.py

status = client.schedules.overall_status()
print(status)

Returns a plain dictionary. The exact fields depend on the server version; inspect the response to discover available keys.

Async usage

All schedules methods are also available on AsyncFigranium. Use await for each call.

async_schedules.py

import asyncio
from figranium import AsyncFigranium
import os

async def main():
    async with AsyncFigranium(api_key=os.environ["FIGRANIUM_API_KEY"]) as client:
        result = await client.schedules.set("task-123", {
            "enabled": True,
            "frequency": "daily",
            "hour": 9,
            "minute": 0,
        })
        print(result["nextRun"])

asyncio.run(main())

Error handling

Schedule methods raise 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 custom headers and per-request timeouts.

Task scheduling

Learn how scheduling works in Figranium.

Errors

Handle FigraniumError responses.

JavaScript SDK

Python SDK

Swift SDK

SchedulesResource: Configure and Inspect Schedules

Schedule type

Examples

Methods

Async usage

Error handling

Tasks

Executions

Request options

Task scheduling

Errors

​Schedule type

​Examples

​Methods

​Async usage

​Error handling

​Related resources

Tasks

Executions

Request options

Task scheduling

Errors

Schedule type

Examples

Methods

Async usage

Error handling

Related resources