[ Support Guide] How to use the API to increase your site's build time limit

last reviewed and confirmed correct by Netlify Support in Sep 2022

What is a build time limit?

The build system at Netlify is one of our metered resources. For example, the build minutes allowed on a Starter plan team are currently 300 minutes each billing cycle (which is monthly).

Sometimes a site’s build command will contain mistake and the build will get stuck forever. (By the way, Netlify didn’t write the build command - the site owner does - so any bugs there are yours :). By “stuck” I mean that the build command stays running but it isn’t actually doing anything useful. It will run - doing nothing - until the “Cancel deploy” button in the web UI is clicked or we do something to terminate it.

The build time limit exists to stop these builds so you don’t use all your build minutes for a single build being stuck for five hours (which would completely use all 300 minutes).

The default build time limit for all sites at Netlify is 15 minutes with 5 additional minutes allowed for any post-processing being done by the build system. So, if your build is stuck, the most build minutes it will use is 15 minutes (or up to 20, if the build succeeded and we are deploying/processing a lot of new tiles). It will automatically be stopped if it goes over that time.

Why would someone want to change the build time limit?

Sometimes builds just take longer than 15 minutes. The build isn’t stuck at all in some cases. You might have many thousands of HTML files, CSS files, and javascript bundles to process. Your site’s build might do build time transformations of thousands of image files. In these cases, the build is doing meaningful work and it isn’t stuck at all. It is just taking longer than 15 minutes to complete all that work.

In cases like those above, someone might want the build to continue until it was completed and not stop at 15 minutes. A longer build time limit would help the build to complete successful because the build is not stuck - it is still working.

How do I change the build time limit?

We haven’t added this build time limit setting to the web UI, not yet at least, but this setting is available in the API today. So, you can use the API itself to change this for any site you have access to in our administrative UI.

There are many ways to use our API directly and this is both allowed and encouraged. Anything you can do via our web UI can be done instead purely via API calls (because our API is what our web UI uses. This article has more details about how that works, if you are curious). Again, because the UI hasn’t been updated yet, the API is currently the only way to see or change this setting.

Probably the easiest way to make API calls directly is using our Netlify CLI tool and I’ll be covering that method below.

The steps to configure the CLI to use the API

  1. Install the CLI locally.
  2. Authenticate by using the CLI login command or using an API key.

You can use the command netlify status to confirm if you are logged in or not. If you are, you are now ready to change the build time limit.

Steps to change the build time limit via API

1. Get the API ID for the site

First, you need to know the API id for your sites. This is found under “Site Name” > Site settings > General > Site details. (If you click the “Site settings” tab at the top for your site, it will take you right there.)

You can see an example in the screenshot below:

In the screenshot above, the API ID is 64f96854-6da4-4d09-98e3-44d56c4b973b and I’ll use that in my examples below. Again, please use the API ID specific to your site and not this API ID above. (You won’t be able to see or change my settings even if you tried and I don’t want you to waste time using my site’s API ID.)

2. Test to see if the API calls work

When using the CLI tool to make API calls, you pass the site API ID using the site_id key like so:

netlify api getSite --data '{ "site_id": "64f96854-6da4-4d09-98e3-44d56c4b973b" }'

This will return a JSON response with the site’s data from the API.

There is another command-line tools useful for parsing JSON named jq. I’ll be using it in these example to extract the property we can about - in this case the build_timelimit. The syntax used by jq is ‘.build_timelimit’ to see that value.

By default it is unset so the API returns no value. Again, the default is 15 minutes but that is a default for all sites. If you haven’t changed the build time limit, you will always get “null” as a response if you query for it:

$ netlify api getSite --data '{ "site_id": "64f96854-6da4-4d09-98e3-44d56c4b973b" }' | jq '.build_timelimit'
null

Note, if you see a message like this:

 ›   TextHTTPError: Unauthorized

That means you are not logged in or there is a problem with your API key.

3. Change the build time limit.

Above, we used getSite to get the site’s settings. We will now use updateSite to change a setting - the build_timelimit setting.

netlify api updateSite --data '{ "site_id": "64f96854-6da4-4d09-98e3-44d56c4b973b", "body": { "build_timelimit": 1800 } }'

This will return all the site settings including the new build_timelimit. You can double check that the setting took effect with the same getSite command above:

$ netlify api getSite --data '{ "site_id": "64f96854-6da4-4d09-98e3-44d56c4b973b" }' | jq '.build_timelimit'
1800

The value changed from null (which means the 900 second default timeout will be used) to 1800 second (30 minutes). It works!

You may notice that the build time limit value above is 1800 and not 30. That is because the time is in seconds - not minutes. 1800 is 30 minutes and that is currently the maximum time that can be set via the API. (Note, our support team can set even longer build time limit than can be done via the API. Please make a new topic if you want see an increase above 30 minutes and our team will be here to assist.)

Summary

​Please let us know if there are any questions about changing this setting via the API with comments below.

One other reminder: you can also use the CLI to make many other changes. Anything you can do in our web UI can be done with the CLI and API instead. (Try netlify api --list to get a complete list of possible API calls the CLI can perform.)

I strongly encourage anyone wanting to experiment with our API to read this related support guide. It covers reverse-engineering how our API calls are made by examining the real world API calls our web UI makes.

A hint from that guide: the browser devtools and the “copy as curl” option in the network tab are the best way to see the correct format for API call data. Once you can see a working API call, it becomes much easier to know the format required for the JSON to send.

I hope this helps people to self-serve making changes to their build time limits until we add an option to the web UI itself. I also hope this helps more people to become comfortable using our APIs directly for any purpose - not just to change this one setting.

1 Like

I’d love to see this added as an option in netlify.toml at some point.

that would be awesome indeed. we (support team) is trying to get a self-serve option for this, either via the UI or the toml file, as it would be better for you (and us). Here’s to hoping, someday!