Timer triggers

A timer function runs on a schedule instead of on a request. It has no public route, and authentication does not apply to it.

Schedule format

A schedule is a standard five-field cron expression — minute, hour, day of the month, month and day of the week:

There is no seconds field. An expression that does not parse is refused when you save the function.

Time zone

Every schedule runs in UTC. The portal's Timezone field is not saved, and the function's Overview always shows UTC. Write the schedule in UTC: 09:00 in Stockholm is 0 7 * * * in summer and 0 8 * * * in winter.

How a run happens

The proxy of a function namespace keeps the schedule. At each scheduled time it wakes the function if it is sleeping, waiting up to 30 seconds for it to start, and then calls it.

What a run receives

A POST to /, with the headers X-Stackship-Trigger-Type: timer and X-Stackship-Function-Name, and this JSON body:

{
  "trigger": "timer",
  "functionName": "nightly-report",
  "scheduledTime": "2026-09-27T07:00:00.0012345Z",
  "schedule": "0 7 * * *"
}

scheduledTime is when the proxy fired the run, in UTC. In a Node.js handler, ctx.triggerType is timer and req.body holds the object above.

Overlapping runs

A proxy waits for a run to finish before it works out the next time, so when a run lasts past the next scheduled time, that time is skipped and the function runs at the one after it.

Important

Every function namespace's proxy runs the schedules of all timer functions in the resource group. With more than one function namespace in the resource group, the function is called once by each of them at every scheduled time, and those runs overlap. Keep a timer function in a resource group with a single function namespace, or make the handler safe to run more than once — see How a request reaches a function.

Failures and retries

A run is not retried. When the handler answers with an error status, runs past the time limit, or the function does not start within 30 seconds, the proxy moves on to the next scheduled time. The outcome is not shown in the portal: log from your handler to see each run in the function's Logs.

Missed runs

The schedule lives in the proxy's memory. Times that pass while the proxy is restarting are not made up afterwards.

Time limit

A run has the same time limit as an HTTP call, 300 seconds — see Time limit.

Sleeping between runs

With the default minimum of 0 replicas, a timer function sleeps until its first run wakes it.

• A timer function that runs an image of your own scales to zero again after its cooldown, 300 seconds by default, and is woken for the next run. A schedule that runs more often than the cooldown keeps it awake.
• A timer function built from the portal stays awake after its first run — see Scale to zero.