> ## Documentation Index
> Fetch the complete documentation index at: https://figranium.dev/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# SchedulesResource: Automate Task Runs with Timers

> Manage recurring task schedules in the Figranium JS SDK. List, set, delete, validate, and inspect cron or interval schedules for any task.

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.

```ts theme={null}
import { Figranium } from "@figranium/sdk";

const figranium = new Figranium({ apiKey: process.env.FIGRANIUM_API_KEY! });
```

## Schedule type

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

```ts theme={null}
type Schedule = {
  enabled: boolean;
  frequency?: "interval" | "hourly" | "daily" | "weekly" | "monthly";
  intervalMinutes?: number;
  hour?: number;
  minute?: number;
  daysOfWeek?: number[];
  dayOfMonth?: number;
  cron?: string;
};
```

* `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:

```ts interval-schedule.ts theme={null}
const intervalSchedule = {
  enabled: true,
  frequency: "interval" as const,
  intervalMinutes: 15,
};

await figranium.schedules.set("task-123", intervalSchedule);
```

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

```ts weekly-schedule.ts theme={null}
const weeklySchedule = {
  enabled: true,
  frequency: "weekly" as const,
  hour: 9,
  minute: 30,
  daysOfWeek: [1, 3],
};

await figranium.schedules.set("task-123", weeklySchedule);
```

## Methods

<AccordionGroup>
  <Accordion title="list">
    Retrieve all tasks that currently have a schedule configured.

    * **HTTP endpoint:** `GET /api/schedules`
    * **Signature:** `schedules.list(options?: RequestOptions): Promise<{ schedules: ScheduleEntry[] }>`

    ```ts list-schedules.ts theme={null}
    const { schedules } = await figranium.schedules.list();

    for (const entry of schedules) {
      console.log(entry.taskId, entry.taskName, entry.schedule.enabled);
    }
    ```

    Returns an object with a `schedules` array. Each `ScheduleEntry` contains `taskId`, `taskName`, `mode`, and the attached `Schedule` object.
  </Accordion>

  <Accordion title="set">
    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 }>`

    ```ts set-schedule.ts theme={null}
    const result = await figranium.schedules.set("task-123", {
      enabled: true,
      frequency: "daily",
      hour: 7,
      minute: 0,
    });

    console.log(result.nextRun); // Unix timestamp of the next scheduled run
    ```

    Returns an object containing the saved `schedule`, a human-readable `description`, and the `nextRun` timestamp (or `null` if the schedule is disabled or invalid).
  </Accordion>

  <Accordion title="delete">
    Remove a task's schedule entirely.

    * **HTTP endpoint:** `DELETE /api/schedules/:taskId`
    * **Signature:** `schedules.delete(taskId: string, options?: RequestOptions): Promise<{ success: boolean }>`

    ```ts delete-schedule.ts theme={null}
    const { success } = await figranium.schedules.delete("task-123");
    ```

    Returns `{ success: boolean }` indicating whether the schedule was removed.
  </Accordion>

  <Accordion title="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(taskId: string, options?: RequestOptions): Promise<{ schedule: Schedule; cron: string | null; description: string | null; isValid: boolean }>`

    ```ts schedule-status.ts theme={null}
    const status = await figranium.schedules.status("task-123");

    console.log(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.
  </Accordion>

  <Accordion title="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(taskId: string, schedule: Schedule, options?: RequestOptions): Promise<{ valid: boolean; description: string | null; cron: string | null; nextRun: number | null }>`

    ```ts describe-schedule.ts theme={null}
    const preview = await figranium.schedules.describe("task-123", {
      enabled: true,
      frequency: "monthly",
      dayOfMonth: 1,
      hour: 6,
      minute: 0,
    });

    console.log(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`.
  </Accordion>

  <Accordion title="overallStatus">
    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>`

    ```ts overall-status.ts theme={null}
    const status = await figranium.schedules.overallStatus();
    console.log(status);
    ```

    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.
  </Accordion>
</AccordionGroup>

## 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](/docs/sdk/js/errors) for retry guidance and error codes.

## Related resources

<CardGroup cols={2}>
  <Card title="Tasks" icon="list-check" href="/docs/sdk/js/resources/tasks">
    Create and manage the tasks you schedule.
  </Card>

  <Card title="Executions" icon="bolt" href="/docs/sdk/js/resources/executions">
    Inspect the runs produced by scheduled tasks.
  </Card>

  <Card title="Request options" icon="sliders" href="/docs/sdk/js/request-options">
    Pass `signal`, `timeoutMs`, and custom headers.
  </Card>

  <Card title="Errors" icon="triangle-exclamation" href="/docs/sdk/js/errors">
    Handle `FigraniumError` responses.
  </Card>
</CardGroup>