Cron Jobs

Cron jobs let you trigger a deployment on a schedule. This is useful for background syncs, cleanup jobs, reminders, and periodic data processing.

CLI quickstart

# create schedule
npx freestyle cron schedule \
  --deployment-id <deployment-id> \
  --cron '*/5 * * * *' \
  --timezone UTC

# inspect recent executions
npx freestyle cron executions <schedule-id> --limit 20

# disable when done
npx freestyle cron disable <schedule-id>

1) Create a deployment with a `scheduled` handler

Your deployment should export a scheduled function. Freestyle calls this handler whenever the schedule runs.

import { freestyle } from "freestyle";

const { deploymentId } = await freestyle.serverless.deployments.create({
  code: `
    export default {
      fetch() {
        return new Response("ok", { status: 200 });
      },
      scheduled(cron) {
        console.log("cron trigger", cron);
      },
    };
  `,
});

2) Create a schedule

const { job } = await freestyle.cron.schedule({
  deploymentId,
  cron: "*/2 * * * * *", // every 2 seconds
  timezone: "UTC",
  payload: { source: "docs-example" }, // optional
  // path: "/internal/cron", // optional
});

console.log(job.schedule.id);

3) Inspect executions

const { executions } = await job.executions({
  limit: 20,
});

console.log(executions.map((e) => ({ id: e.id, status: e.status })));

Execution statuses include: queued, running, succeeded, failed, retry.

4) Monitor success rate

const now = new Date();
const oneHourAgo = new Date(now.getTime() - 60 * 60 * 1000);

const metrics = await job.successRate({
  start: oneHourAgo,
  end: now,
});

console.log(metrics.successRate);

5) Pause or resume a schedule

await job.disable();
await job.enable();

List schedules for a deployment

const { jobs } = await freestyle.cron.list({ deploymentId });
console.log(jobs.map((j) => j.schedule.id));

End-to-end example

import "dotenv/config";
import { freestyle } from "freestyle";

const { deploymentId } = await freestyle.serverless.deployments.create({
  code: `export default {
    fetch() {
      return new Response("Hello, World!", { status: 200 });
    },
    scheduled(cron) {
      console.log(cron);
    },
  };`,
});

const { job } = await freestyle.cron.schedule({
  deploymentId,
  cron: "*/2 * * * * *",
  timezone: "UTC",
});

await new Promise((resolve) => setTimeout(resolve, 11_000));

const { executions } = await job.executions({ limit: 5 });
console.log(executions);

await job.disable();

For high-frequency schedules, keep handlers idempotent so retries are safe.