Background Functions overview

For the complete documentation index, see llms.txt

This feature is available on Credit-based plans, including Free, Personal, and Pro and on Enterprise plans. Learn more.

Netlify’s Background Functions provide an option for serverless functions that run for up to 15 minutes and don’t need to complete before a visitor can take next steps on your site. For tasks like batch processing, scraping, and slower API workflow execution, they may be a better fit than synchronous functions.

How background functions work

Background functions are longer-running functions that are processed as background tasks using asynchronous invocation.

When a function is invoked asynchronously, there is an initial 202 success response that indicates that the function was successfully invoked. The function will run separately in the background until it completes or it reaches the 15 minute execution limit. If function invocation returns an error, a retry happens after one minute. If it fails again, another retry happens two minutes later.

When a background function is successfully executed, you generally pass the result to a destination other than the originating client.

Like all Netlify Functions, background functions are version-controlled, built, and deployed along with the rest of your Netlify site. Background functions are deployed with the default values, and you can configure and monitor them along with your other functions.

Background functions don’t support response streaming because they don’t return responses.

Create background functions

To enable background mode on a function, set background: true in the function’s config. For example:

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

export default async (req: Request) => {
  // Long-running work. The client has already received a 202 response.
}

export const config: Config = {
  background: true,
  path: "/process",
}

Background function syntax is otherwise identical to synchronous function syntax — a default export that receives a web platform Request and a Netlify-specific Context object. The difference is that the client receives an empty 202 response immediately, so you generally pass the invocation result to a destination other than the originating client.

You can also configure background mode through netlify.toml:

[functions.process]
  background = true

Legacy filename convention

Before config.background was introduced, background mode was enabled by naming the function file with a -background suffix.

This convention is still fully supported and continues to work, but new functions should prefer the config.background property described above — keeping configuration alongside the rest of your function’s settings is easier to read, easier to toggle, and easier for AI coding agents to discover.

For example, the following file would deploy as a background function called hello-background:

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

export default async (req: Request, context: Context) => {
  // Long-running work. The client has already received a 202 response.
}

export const config: Config = {
  path: "/process",
}

The suffix also works on subdirectory-based functions (netlify/functions/hello-background/index.mts).

More Background Functions resources

Did you find this doc useful?

Your feedback helps us improve our docs.