Workflows

A workflow runs a saved package's export once, in the background. Use it for three things a job or an execute call can't do well:

• Run something once at a set time. Pass runAt, up to a year ahead. The scheduler checks every minute.
• Run something longer than execute allows. A workflow's export gets about 4.5 minutes of wall clock, against 90 seconds for execute. Good for batch sweeps, backfills and migrations.
• Kick off work and walk away. Start it now, close the chat, and check on it later.

For a recurring schedule, use a job instead.

Start one

const wf = await minion.workflows.create({
  package: 'storage-sweep',
  export: './sweep',
  params: { day: '2026-05-08' },
  runAt: new Date(Date.now() + 3_600_000).toISOString(),
  idempotencyKey: 'storage-sweep:2026-05-08',
})

Leave out runAt to start now. Leave out export to run the package's default export. Inside a package's own code, package defaults to that package.

Always pass an idempotencyKey that names the logical piece of work. Calling create again with the same key returns the existing workflow (existing: true), even a finished or cancelled one, instead of starting a second run.

The export runs as you and counts as a job run. Your plan caps how many workflows can be unfinished at once; the smallest plan allows one.

Check on it

const { workflows } = await minion.workflows.list({ status: ['pending', 'running'] })

A workflow moves through pending (waiting for runAt), queued and running, then ends as succeeded, failed, timed_out, rejected or cancelled. Each entry has the runId; open it with minion.runs.get({ id: runId }) for logs and the error. One-off runs also show on the Jobs page .

Cancel one

await minion.workflows.cancel({ id: 'wf_123' })

You can cancel a workflow until its export starts. A running export can't be stopped: the result says cancelled: false with status running, and it finishes or times out on its own. Cancelling a finished workflow is a safe no-op. A cancelled workflow keeps its idempotency key, so use a new key to run that work again.

Members can cancel their own workflows. Owners and admins can cancel any.

When to use something else

• Every day at 8: a job with a cron schedule in package.json#minion.jobs.
• When something happens: an event subscription or an inbound webhook .
• Remind a person: a task reminder . It notifies someone; a workflow runs code.
• Work bigger than 4.5 minutes: split it. Have each run handle one page and keep a cursor in package storage , then start the next workflow from the end of the current one.