Cron Functions

Schedule any deployed function to run automatically on a time-based schedule using standard cron expressions.

How it works

Create a cron schedule that points to an existing deployed function. The Koolbase scheduler checks every minute for due schedules and fires the function automatically. The function receives a context with the cron ID, expression, and fired time.

Prerequisite

The function must already be deployed before you can schedule it. Deploy it first via the dashboard or CLI, then create a cron schedule pointing to it.

Cron expression syntax

Koolbase uses standard 5-field cron expressions:

┌───────── minute (0–59)
│ ┌───────── hour (0–23)
│ │ ┌───────── day of month (1–31)
│ │ │ ┌───────── month (1–12)
│ │ │ │ ┌───────── day of week (0–6, Sunday = 0)
│ │ │ │ │
* * * * *

* * * * *Every minute

*/5 * * * *Every 5 minutes

0 9 * * *Every day at 9:00 AM UTC

0 0 * * 1Every Monday at midnight UTC

0 0 1 * *First day of every month at midnight UTC

30 8 * * 1-5Monday–Friday at 8:30 AM UTC

Timezone

All cron schedules run in UTC. Convert your local time to UTC when writing expressions.

Create via dashboard

Go to your project in app.koolbase.com → Functions → select a function → Cron tab → Add Schedule.

Create via CLI

# Add a cron schedule
koolbase crons add send-daily-report --cron "0 9 * * *" --project <project_id>

# List all schedules
koolbase crons list --project <project_id>

# Disable a schedule
koolbase crons toggle <cron_id> --disable --project <project_id>

# Re-enable a schedule
koolbase crons toggle <cron_id> --enable --project <project_id>

# Delete a schedule
koolbase crons delete <cron_id> --project <project_id>

Create via API

curl -X POST https://api.koolbase.com/v1/projects/<project_id>/crons \
  -H "Authorization: Bearer <token>" \
  -H "Content-Type: application/json" \
  -d '{
    "function_name": "send-daily-report",
    "cron_expression": "0 9 * * *"
  }'

{
  "id": "18f79c3a-1965-44a5-8ff2-1d35ac58ede8",
  "project_id": "...",
  "function_name": "send-daily-report",
  "cron_expression": "0 9 * * *",
  "enabled": true,
  "next_run_at": "2026-03-30T09:00:00Z",
  "created_at": "2026-03-29T23:14:55Z"
}

Function context

When a cron fires your function, the context includes cron metadata in the request:

export async function handler(ctx) {
  // ctx.request contains cron metadata
  const { cron_id, expression, fired_at } = ctx.request;

  console.log(`Cron ${expression} fired at ${fired_at}`);

  // Your logic here
  await ctx.db.insert('reports', {
    generated_at: fired_at,
    type: 'daily',
  });

  return { ok: true, fired_at };
}

Future<Map<String, dynamic>> handler(Map<String, dynamic> ctx) async {
  final request = ctx['request'] as Map<String, dynamic>;
  final firedAt = request['fired_at'] as String?;

  // Your logic here
  final db = ctx['db'] as Map<String, dynamic>;
  await (db['insert'] as Function)('reports', {
    'generated_at': firedAt,
    'type': 'daily',
  });

  return {'ok': true, 'fired_at': firedAt};
}

API reference

POST/v1/projects/{id}/cronsCreate a cron schedule

GET/v1/projects/{id}/cronsList all cron schedules

PATCH/v1/projects/{id}/crons/{cron_id}Enable or disable a schedule

DELETE/v1/projects/{id}/crons/{cron_id}Delete a schedule

Limits

Minimum intervalEvery 1 minute

Execution timeoutSame as function timeout (max 30s)

TimezoneUTC only

Retry on failureNo — cron fires are not retried

Missed runsNot backfilled — only fires at next scheduled time