Running a workflow on a schedule

A schedule trigger starts a workflow on a cadence you write as a cron expression. Flowker records every firing as an occurrence, so a firing that could not happen on time is not lost. It waits in a parked list until you run it or discard it. Use this page to write the trigger, confirm the cadence, and work the parked list.

Before you start

A workflow in draft status. Only a draft workflow accepts an edit, so write the trigger before you activate it. See Getting started with Flowker for the create-and-activate path.
The worker binary running with the scheduler enabled. The variable SCHEDULER_ENABLED resolves to true unless you set it to false, and the queue needs SCHEDULER_REDIS_HOST. With no host the worker binary does not start and no scheduled workflow fires. Check that variable first when your schedules never fire. See Scheduler variables.
The read permission on the workflows resource to list occurrences and counts, and update on the same resource to run or discard one.

Step 1: Write the schedule trigger node

Triggers come built in. You discover them in the catalog, and you never create one. Get a catalog trigger returns the schedule trigger’s JSON Schema from the running instance:

curl -s http://localhost:4021/v1/catalog/triggers/schedule | jq -r '.schema' | jq .

The schedule trigger is a node with type: "trigger" and these fields in its data:

Field	When you set it	Value
`triggerType`	Always	`"schedule"`.
`cron`	Always	The cadence, as a standard 5-field cron expression: `minute hour day-of-month month day-of-week`.
`timezone`	Optional	The IANA identifier of the zone the cron fields belong to, such as `"America/Sao_Paulo"`. Defaults to `UTC`; an empty or unresolvable timezone is also evaluated as `UTC`.
`enabled`	Optional	`false` stops the schedule from firing while the workflow stays active. Defaults to `true`.

What the cron expression accepts

Five fields, separated by spaces. Each field takes *, a value, a list (0,30), a range (9-17), or a step (*/15, 9-17/2). Day-of-week runs 0–7, where both 0 and 7 mean Sunday. When you restrict day-of-month and day-of-week at the same time, the schedule fires on a day that matches either field. The expression 0 9 13 * 5 fires on the 13th and on every Friday. One minute is the finest cadence a 5-field expression can express. For anything faster, take the call in as it arrives with a webhook trigger. Flowker checks the expression when you save the workflow and again when you activate it, and answers FLK-0117 when it does not hold. These forms do not hold:

A six-field expression, such as */30 * * * * *.
A macro, such as @daily or @every 5m.
A named day or month, such as MON, MON-FRI or sun.
An L or # token, such as 0 9 L * * or 0 9 * * 5#2.
A value outside its field’s range, such as 60 minutes, 24 hours, day-of-month 0 or 32, month 13, or day-of-week 8.
A /0 step.

How the timezone works

The cron fields are wall-clock time in the zone you name, and every time the API returns is UTC. A 0 9 * * * schedule in America/Sao_Paulo reports 12:00Z. A zone that observes daylight saving keeps the wall-clock hour across the change: the same expression in America/New_York reports 14:00Z in winter and 13:00Z in summer.

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Daily settlement",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "0 9 * * *",
    "timezone": "America/Sao_Paulo"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Poll for new statements",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "*/15 * * * *"
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Weekday reconciliation",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "30 7 * * 1-5",
    "timezone": "America/Sao_Paulo",
    "enabled": false
  }
}

{
  "id": "trigger-1",
  "type": "trigger",
  "name": "Month-open batch",
  "position": { "x": 0, "y": 0 },
  "data": {
    "triggerType": "schedule",
    "cron": "0 3 1 * *",
    "timezone": "UTC"
  }
}

Step 2: Activate the workflow and read the cadence

Save the workflow

Send the node with the rest of your workflow to Create a workflow, or to Update a workflow if the draft already exists. Flowker validates the cron here.

Check the cadence before you commit to it

List upcoming scheduled occurrences computes the next firings straight from the trigger, so you can read them while the workflow is still a draft.

curl -s "http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/upcoming?limit=3" | jq .

{
  "occurrences": [
    { "scheduledFor": "2026-08-01T12:00:00Z" },
    { "scheduledFor": "2026-08-02T12:00:00Z" },
    { "scheduledFor": "2026-08-03T12:00:00Z" }
  ]
}

limit takes 1 to 50 and defaults to 10. A value outside that range answers FLK-0304.

Activate it

Call Activate a workflow. The leader-gated producer sweeps on a 60-second default interval. After a successful sweep, Flowker records and queues the next occurrence for its slot.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/activate | jq .

Flowker records only the next firing, never a calendar of future firings. When that occurrence runs, the engine records the firing after it, so the cadence carries itself forward one occurrence at a time.

Step 3: See which occurrences did not run

An occurrence parks when the engine reaches it more than a minute after its slot and nobody has asked for that slot to run. Common causes are a service that was down, a queue that was behind, or a process that restarted. Flowker never runs a parked occurrence on its own. It holds it for your decision, in the pending-review state. A parked occurrence stays available to the run and discard endpoints. Flowker never back-fills a slot that passed. So the parked list holds the firings Flowker had already recorded and could not run. It does not hold one entry for every slot that went by during an outage. The cadence itself resumes from the next future slot. An occurrence is skipped when the engine took it up and closed it without running the workflow. The scheduler never runs a skipped occurrence again. A skipped occurrence carries a skipReason, and the run and discard endpoints do not accept it:

`skipReason`	What happened
`active-run`	Another run of this workflow was still going. A schedule runs one occurrence at a time, so this firing stood down.
`workflow-gone`	The workflow was deleted, or it was not active when the occurrence reached the engine.
`execution-duplicate`	The work for that slot had already run, so the engine did not run it twice.

The two classes do not split on timing. One thing timing does decide: a late slot you never asked to run lands in the parked list, never in the skipped list. After you ask for a parked slot to run, its age stops holding it back. The engine then takes it up like any other occurrence, and all three reasons above can close it. So a scheduledFor far in the past is normal in the skipped list, and it does not mean the slot fired on time. Step 4 covers what your own run can end in. Three reads cover the whole picture:

List the parked occurrences of one workflow

List parked scheduled occurrences returns them oldest first.

curl -s http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed | jq .

{
  "occurrences": [
    {
      "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30",
      "workflowId": "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a",
      "status": "pending-review",
      "cronExpr": "0 9 * * *",
      "timezone": "America/Sao_Paulo",
      "scheduledFor": "2026-07-29T12:00:00Z",
      "attempts": 0,
      "createdAt": "2026-07-29T11:00:04Z",
      "updatedAt": "2026-07-30T08:12:41Z"
    }
  ]
}

scheduledFor is the slot the occurrence stands for, and status is what decides whether you can act on it.This route takes no limit and no page cursor, and it returns at most 100 occurrences. Plan a bulk recovery around that: work the rows you get, then read the list again.The count below reports the total in pending-review. The parked list can hold more rows than that count, because it also includes missed occurrences. The missed state is short-lived: a late slot holds it while the engine parks the slot as pending-review. The run and discard endpoints do not accept that state, so read the list again and act once the row shows pending-review. Discarding the whole list also covers every occurrence pending review, not only the 100 a single read shows you.

List the skipped occurrences

List skipped scheduled occurrences returns them oldest first, each with its skipReason. When supplied, limit takes 1 to 50. When omitted, it defaults to 100.

curl -s "http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/skipped?limit=10" | jq '.occurrences[] | {scheduledFor, skipReason}'

{ "scheduledFor": "2026-07-28T12:00:00Z", "skipReason": "active-run" }

Repeated active-run skips mean the workflow takes longer than the gap between two firings. Widen the cadence, or make the workflow finish faster.

Count what is waiting across every workflow

Count pending-review occurrences answers for the whole tenant in one call, which is what you poll for a review badge. The map is sparse: a workflow with nothing waiting is absent from it.

curl -s http://localhost:4021/v1/workflows/schedule/pending-review-counts | jq .

{
  "counts": {
    "019c96a0-0ac0-7de9-9f53-9cf842a2ee5a": 2
  }
}

Add ?workflowIds=<id>,<id> to scope the counts to the workflows you care about.

Both lists answer 200 with an empty occurrences array for a workflow id your tenant does not own, so an empty list means “nothing to review here”. Flowker exposes the underlying schedule data through its upcoming, parked, and pending-review-count APIs. Consult the Console documentation for UI guidance.

Step 4: Run or discard a parked occurrence

Run and discard act on an occurrence whose status is pending-review. Any other state answers FLK-0755, which also makes a repeated call safe: the second call answers the same error instead of acting twice. Your own run puts the occurrence in one of those other states: it leaves pending-review straight away. A run you ask for leaves the parked list at once, and the age of the slot no longer holds it back. It does not promise that the workflow runs:

The workflow runs. The execution appears in List executions for that workflow.
The engine closes the occurrence as skipped. It leaves the parked list for the skipped list with one of the three reasons above. An active-run reason means another run of the workflow was still in progress. A workflow-gone reason means the workflow was not active when your run reached the engine. An execution-duplicate reason means the work for that slot had already run.

After your run, the scheduler never runs a skipped occurrence again, and the run and discard endpoints do not accept it. Read both lists before you conclude anything about a slot you tried to recover. The skipped row may record the refusal of your recovery, not of the original firing. Keep the workflow active while you work the list. A run reloads the workflow, and a workflow that is not active closes the occurrence as a workflow-gone skip instead of running it.

Run one occurrence

Run a parked occurrence moves it to queued and enqueues a force-run on the same execution path a scheduled firing uses. The delayed-task forwarder checks every second by default. Actual start time depends on worker availability and queue capacity.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30/run | jq '{id, status}'

{ "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30", "status": "queued" }

The run covers that one slot. It does not shift the cadence: the next firing stays the one the engine already planned.

Discard one occurrence

Discard a parked occurrence moves it to discarded, which is terminal. The occurrence never executes and leaves the parked list.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30/discard | jq '{id, status}'

{ "id": "019c96a0-3f21-7b44-8d0e-5a1c7e2b9f30", "status": "discarded" }

Clear the whole parked list of one workflow

Discard all parked occurrences discards, in a single write, every occurrence of that workflow pending review, and reports how many it moved.

curl -s -X POST http://localhost:4021/v1/workflows/019c96a0-0ac0-7de9-9f53-9cf842a2ee5a/schedule/missed/discard-all | jq .

{ "discarded": 7 }

With nothing pending review it answers 200 with "discarded": 0, so a repeat call is safe.

A discard cannot be undone, and it never runs anything. Read the parked list before you clear it.Discarding all parked occurrences covers exactly the occurrences of that one workflow, in your tenant, pending review. It leaves the schedule itself running and leaves the upcoming occurrences alone. It does not touch another workflow’s occurrences, or occurrences that already ran, failed, were skipped, or were discarded earlier.

Confirm it worked

The cadence is healthy when List upcoming scheduled occurrences returns future slots and the parked list stays short.
A run worked when the occurrence has left the parked list and the execution shows up in List executions for that workflow.
A discard worked when the occurrence has left the parked list and the pending-review count for that workflow has dropped.

Change or pause a cadence

Only a draft workflow accepts an edit, so a cadence change is four calls:

Deactivate the workflow. Flowker stops recording new occurrences for it.
Move it to draft.
Update the workflow with the new cron, timezone, or enabled value.
Activate it. The leader-gated producer sweeps on a 60-second default interval. After a successful sweep, Flowker records and queues the next occurrence from the new cadence.

Flowker does not back-fill the slots that passed while the workflow was inactive. The parked occurrences survive all four steps. They stay listed and stay actionable once the workflow is active again.

A parked occurrence Flowker recorded before the change remains pending review. Read the parked list after a cadence change, and clear anything you no longer want.

When something goes wrong

Code	When it happens	What to do
`FLK-0117`	You save or activate the workflow.	The cron is not a standard 5-field expression. Compare it against What the cron expression accepts.
`FLK-0118`	You list the upcoming occurrences.	The workflow carries no schedule trigger, or its cron is not an expression Flowker can compute. Check the trigger node’s `triggerType` and `cron`.
`FLK-0100`	You list the upcoming occurrences.	No workflow in your tenant has that id.
`FLK-0002`	Any of these calls.	A path id is not a valid UUID.
`FLK-0304`	You list upcoming or skipped occurrences.	`limit` is outside `1`–`50`.
`FLK-0755`	You run or discard an occurrence.	The occurrence is not pending review. Your own run may have moved it on already, or it may have run, been skipped, or been discarded. Read the parked list and the skipped list before you call again.
`FLK-0760`	You run or discard an occurrence.	No occurrence of that workflow has that id. Take the id from the parked list of the same workflow.

Two failures answer no error code:

The upcoming list shows occurrences, but nothing ever runs. The API computes the cadence on its own, while the worker binary is what fires it. Confirm that the worker runs and that you set SCHEDULER_REDIS_HOST. See Scheduler variables.
Flowker records nothing new for an active workflow. Check enabled on the trigger node: false keeps the workflow active and its schedule quiet.

Overview

Guides

Console

Operations

Running a workflow on a schedule

Before you start

Step 1: Write the schedule trigger node

What the cron expression accepts

How the timezone works

Step 2: Activate the workflow and read the cadence

Step 3: See which occurrences did not run

Step 4: Run or discard a parked occurrence

Confirm it worked

Change or pause a cadence

When something goes wrong

What’s next

Configuring a webhook trigger

Workflow design guide

​Before you start

​Step 1: Write the schedule trigger node

​What the cron expression accepts

​How the timezone works

​Step 2: Activate the workflow and read the cadence

​Step 3: See which occurrences did not run

​Step 4: Run or discard a parked occurrence

​Confirm it worked

​Change or pause a cadence

​When something goes wrong

​What’s next

Configuring a webhook trigger

Workflow design guide

Before you start

Step 1: Write the schedule trigger node

What the cron expression accepts

How the timezone works

Step 2: Activate the workflow and read the cadence

Step 3: See which occurrences did not run

Step 4: Run or discard a parked occurrence

Confirm it worked

Change or pause a cadence

When something goes wrong

What’s next