Background Functions overview
This feature is in BETA and may not be available on all plans.
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 deployment options, and you can configure and monitor them along with your other functions.
# Create background functions
You can create background functions in TypeScript, JavaScript, or Go.
To get started, create a function file in your functions directory and append the name with -background. For example, netlify/functions/hello-background.ts. Based on the filename, Netlify will deploy a background function that can be called on the following endpoint, relative to the base URL of your site: /.netlify/functions/hello-background.
Background function syntax is similar to synchronous function syntax. The function file exports a handler method and Netlify provides the event and context parameters when the function is invoked. But, with background functions, you generally pass the function result to a destination other than the originating client.
Check out our create functions doc to learn more about how to name your function and the background function format, including a detailed background function example that you can reference.
Want to use background functions with Next.js?
If you have a Next.js site on Netlify, you can use advanced API routes for background functions. The endpoint for background functions with Next.js differs from the endpoint described above. Read more about background API routes for Next.js.
# Invoke background functions
Typically, you invoke a background function with a POST request to your endpoint, so that you can pass parameters as needed. You can also trigger background functions on Netlify events and Identity events.
You can then reference the function logs to observe and troubleshoot the background functions as they run.
# More Background Functions resources
Did you find this doc useful?
Your feedback helps us improve our docs.