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 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 the event and context parameters when the function is invoked.

To make the handler method a scheduled function, wrap it with the schedule function as you export it.

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

import { Handler, HandlerEvent, HandlerContext, schedule } from "@netlify/functions";

const myHandler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
  console.log("Received event:", event);

    return {
        statusCode: 200,
    };
};

const handler = schedule("@hourly", myHandler)

export { handler };
// YOUR_BASE_DIRECTORY/netlify/functions/test-scheduled-function.js

const { schedule } = require("@netlify/functions");

const handler = async function(event, context) {
    console.log("Received event:", event);

    return {
        statusCode: 200,
    };
};

exports.handler = schedule("@hourly", handler);

# 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 the event and context parameters when the function is invoked.

// YOUR_BASE_DIRECTORY/netlify/functions/test-function.ts

import { Handler, HandlerEvent, HandlerContext } from "@netlify/functions";

const handler: Handler = async (event: HandlerEvent, context: HandlerContext) => {
    console.log("Received event:", event);

    return {
        statusCode: 200,
    };
};

export { handler };

// YOUR_BASE_DIRECTORY/netlify/functions/test-function.js

exports.handler = async function(event, context) {
    console.log("Received event:", event);

    return {
        statusCode: 200,
    };
};

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

# ./netlify.toml

[functions."test-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 * * * *)

# Feedback

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