Background Functions overview
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.
Background functions don’t support response streaming because they don’t return responses.
# 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.mts. 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 file has a default export with a function that receives a web platform Request and a Netlify-specific Context object on each invocation. But, with background functions, the client receives an empty response while the execution happens in the background, so you generally pass the invocation result to a different destination.
Check out our get started with functions doc to learn more about how to name your function and the background function format.
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.