Schedules

Schedule routes manage cron, interval, and one-shot triggers. The integrated schedule_manager runs inside the server process; creating a schedule registers it for in-process polling.

In addition to the routes here, schedules can be created implicitly by registering a workflow that declares @workflow.with_options(schedule=cron(...)). Auto-schedules are named <workflow>_auto and can be disabled globally with [flux.scheduling].auto_schedule_enabled = false.

POST /schedules

Create a schedule.

• Body (ScheduleRequest):

  {
    "name": "nightly-report",
    "workflow_name": "report",
    "workflow_namespace": "default",
    "schedule_config": { "type": "cron", "expression": "0 2 * * *" },
    "description": "...",
    "input_data": { },
    "run_as_service_account": "scheduler-sa"
  }

  schedule_config accepts {"type": "cron", "expression": "..."}, {"type": "interval", "seconds": <n>}, or {"type": "once", "run_at": "<iso8601>"}.

• Permission: schedule:*:manage. When auth is enabled, run_as_service_account is required and must resolve to an existing service-account principal (400 otherwise).

• Response: ScheduleResponse with id, name, workflow_name, workflow_namespace, schedule_config, description, input_data, run_as_service_account, enabled, created_at, updated_at, next_run_at.

• 404: workflow does not exist.

GET /schedules

List schedules.

• Query:
  • workflow_name=<name> — filter to one workflow.
  • active_only=true (default) — exclude paused schedules.
  • limit, offset — pagination.
• Permission: any authenticated identity; results are filtered per-row to schedules whose bound workflow the caller has workflow:{ns}:{name}:read on.
• Response: array of ScheduleResponse.

GET /schedules/{schedule_id}

Show a schedule. Accepts either the schedule’s UUID or its name.

• Permission: workflow:{ns}:{name}:read on the schedule’s bound workflow.
• Response: ScheduleResponse.
• 404: schedule not found.

PUT /schedules/{schedule_id}

Update an existing schedule. The REST API supports this; the CLI does not — there is no flux schedule update. To change a schedule via the CLI you must delete and recreate.

• Body (ScheduleUpdateRequest): any of schedule_config, description, input_data, run_as_service_account. Omitted fields are left unchanged.
• Permission: schedule:*:manage.
• Response: updated ScheduleResponse.
• 400: when auth is enabled and run_as_service_account is provided but doesn’t resolve to a service account.
• 404: schedule not found.

POST /schedules/{schedule_id}/pause

Mark a schedule paused. Accepts ID or name.

• Permission: schedule:*:manage.
• Response: updated ScheduleResponse.

POST /schedules/{schedule_id}/resume

Reactivate a paused schedule.

• Permission: schedule:*:manage.
• Response: updated ScheduleResponse.

DELETE /schedules/{schedule_id}

Remove a schedule. Accepts ID or name.

• Permission: schedule:*:manage.
• Response: {"status": "success", "message": "..."}.

GET /schedules/{schedule_id}/history

List executions launched by a schedule.

• Query: limit=50, offset=0.

• Permission: schedule:*:read.

• Response:

  {
    "schedule_id": "...",
    "workflow_name": "report",
    "entries": [
      {
        "execution_id": "...",
        "workflow_name": "report",
        "state": "COMPLETED",
        "started_at": "2026-05-14T02:00:01Z",
        "completed_at": "2026-05-14T02:00:09Z",
        "error": null
      }
    ],
    "total": 42,
    "limit": 50,
    "offset": 0
  }

  History is queried via the schedule manager’s get_schedule_history(schedule_id, ...). The query filters on executions.schedule_id, so history is scoped to the specific schedule — schedules that point at the same workflow each return only their own executions. The started_at and completed_at timestamps are populated from the execution’s event log.