Background Functions overview
This feature is available onCredit-based plans, including Free, Personal, and Pro and onEnterprise plans.
If you are on the legacy Pro plan, this feature is available only until December 15, 2025.
To keep using the feature, consider switching to an updated plan.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
Section titled “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 initial202 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 thedefault deployment options, and you canconfigure andmonitor them along with your other functions.
Background functions don’t support response streaming because they don’t return responses.
Create background functions
Section titled “Create background functions”You cancreate background functions in TypeScript,JavaScript, orGo.
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 platformRequest and aNetlify-specificContext 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 ourget started with functions doc to learn more about how toname your function and thebackground function format.
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 aboutbackground API routes for Next.js.
Invoke background functions
Section titled “Invoke background functions”Typically, you invoke a background function with aPOST request to your endpoint, so that you can pass parameters as needed. You can also trigger background functions onNetlify events andIdentity events.
You can then reference thefunction logs to observe and troubleshoot the background functions as they run.
More Background Functions resources
Section titled “More Background Functions resources”Did you find this doc useful?
Your feedback helps us improve our docs.