Platform primitives /Functions /

Scheduled Functions

This feature is in Beta.

Scheduled Functions is a feature of Netlify Functions that enables you to run functions on a regular and consistent schedule, much like a cron job. Scheduled functions can do almost anything that serverless functions do today, though some tasks are better suited to scheduled functions than others.

For example, you may want to:

Invoke a set of APIs to collate data for a report at the end of every week
Backup data from one data store to another at the end of every night
Build and/or deploy all your static content every hour instead of for every authored or merged pull request
Or anything else you can imagine you might want to invoke on a regular basis! Note that scheduled functions don’t work with payloads or POST request data. When you need to work with payloads, you should use either a synchronous or background function instead.

# Getting started

The Scheduled Functions beta is enabled by default for all accounts. To try the feature, write a scheduled function for your site.

Keep the default deployment options, such as memory and execution time limits, in mind as you work with scheduled functions.

# Writing a scheduled function

Scheduled functions use the “cron expression” format used by tools like crontab and are executed according to the UTC timezone. For example, the cron expression 0 0 * * * will run a scheduled function every day at midnight UTC. We also support the extensions in the RFC, except for the @reboot and @annually specifications. With extensions, the expression 0 0 * * * can be written as @daily. There are two ways to specify a cron expression for a scheduled function — inline in function code or in netlify.toml.

Specifying cron expressions inline only works for TypeScript and JavaScript

If you use a function language other than TypeScript or JavaScript, you must specify your cron expression in netlify.toml.

# Cron expression inline in function code

First, make sure you install the @netlify/functions npm module to your local project directory:

npm install @netlify/functions

Then, create a scheduled function in your Netlify functions directory using the general syntax of a synchronous function. Netlify provides a web platform Request and a Netlify-specific Context object on each invocation.

For scheduled functions, the request body is a JSON-encoded object containing a next_run property. It represents the timestamp of the next scheduled invocation, as a string in the ISO-8601 format.

To set the schedule of a function, export a config object with a schedule property containing the cron expression.

// YOUR_BASE_DIRECTORY/netlify/functions/test-scheduled-function.mts

import type { Config } from "@netlify/functions"

export default async (req: Request) => {
    const { next_run } = await req.json()

    console.log("Received event! Next invocation at:", next_run)
}

export const config: Config = {
    schedule: "@hourly"
}

// YOUR_BASE_DIRECTORY/netlify/functions/test-scheduled-function.mjs

export default async (req) => {
    const { next_run } = await req.json()

    console.log("Received event! Next invocation at:", next_run)
}

export const config = {
    schedule: "@hourly"
}

# Cron expression in `netlify.toml`

If you prefer to keep your cron expressions in one file and separate from your function code, you can specify them in the netlify.toml configuration at the root of your repository.

First, create a function in your Netlify functions directory using the general syntax of a synchronous function. Netlify provides a web platform Request and a Netlify-specific Context object on each invocation.

For scheduled functions, the request body is a JSON-encoded object containing a next_run property. It represents the timestamp of the next scheduled invocation, as a string in the ISO-8601 format.

// YOUR_BASE_DIRECTORY/netlify/functions/test-scheduled-function.mts

export default async (req: Request) => {
    const { next_run } = await req.json()

    console.log("Received event! Next invocation at:", next_run)
}

// YOUR_BASE_DIRECTORY/netlify/functions/test-scheduled-function.mjs

export default async (req) => {
    const { next_run } = await req.json()

    console.log("Received event! Next invocation at:", next_run)
}

Then, specify the function as a scheduled function in your configuration file:

# ./netlify.toml

[functions."test-scheduled-function"]
schedule = "@hourly"

# Developing and debugging scheduled functions

Scheduled functions only run on published deploys and, similar to event-triggered functions, you can’t invoke them directly with a URL. This means that you can’t test with deploy previews, for example.

Therefore, the best way to test a scheduled function is to use Netlify Dev to serve your scheduled function locally and then use the netlify functions:invoke command to invoke it. Note that Netlify Dev will not execute the scheduled function on any kind of schedule — the invoke command only allows you to debug the function code invocation.

You can also invoke functions locally on the URL path but these invocations are purely for interactive debugging. Netlify Dev wraps the function response with a note that this URL invocation isn’t possible in production.

Alternatively, you can create a new test site to experiment with scheduled functions as part of published deploys.

Once you deploy your code, the deployed function should appear on the Functions page of the Netlify UI with a Scheduled badge. The function will show a next execution date and time, converted to the user’s timezone.

Example of a function list on the Functions page of the Netlify UI

Select the scheduled function to access the function’s schedule and logs.

Example of a scheduled function’s details in the Netlify UI

# Supported cron extensions

@yearly: once a year, on January 1st 00:00 (0 0 1 1 *)
@monthly: every month, on the first day of the month, at 00:00 (0 0 1 * -)
@weekly: every Sunday, 00:00 (0 0 * * 0)
@daily: once a day, at 00:00 (0 0 * * *)
@hourly: every hour, at minute 0 (0 * * * *)

# Limitations

Scheduled functions have a 30 second execution limit. Background functions are more appropriate for tasks that must run longer.
Scheduled functions only run on published deploys. They don’t run on Deploy Previews or branch deploys.
You can’t invoke scheduled functions directly with a URL. Review the developing and debugging section above for how to test.
Scheduled functions don’t support response streaming because they don’t return a response body.
Scheduled functions don’t work with Split Testing because Split Testing relies on branch deploys and scheduled functions only run on published deploys.
Scheduled functions don’t work with sites that have site-wide basic password protection enabled as the protection applies to all parts of your site, including function endpoints. Netlify doesn’t have access to authentication information when executing scheduled functions. Consider using basic authentication with custom HTTP headers instead to protect only the sections of the site that need it and exclude the functions.

# Feedback

We’d love to hear your thoughts on how we can make Scheduled Functions better. Please visit our Forums to join the conversation.

Last updated: September 6, 2024

Did you find this doc useful?

Your feedback helps us improve our docs.