Setting Timeout for Curl Request

You can set a timeout for connecting to the server with the --connect-timeout command-line option and a timeout for the total request time with the -m or --max-time command-line option. The waiting time is specified in seconds. This is the time during which the request must be processed or canceled. In this Curl timeout example, we set the timeout for sending requests to the ReqBin echo URL. Click the Run button to execute the Curl Timeout Example online and see the results.
Setting Timeout for Curl Request Run
curl --connect-timeout 5 https://reqbin.com/echo
Updated: Viewed: 39187 times

What is Curl?

Curl is an open-source command-line tool and cross-platform library (libcurl) for transferring data to and from a server. Curl supports all popular internet protocols, including HTTP and HTTPS. Developers use Curl to test APIs, automate tasks, and support SSL certificates and HTTP Cookies. Curl works on all modern platforms like Windows, Linux, and macOS.

What is Timeout?

The waiting time is called a timeout. Curl sends requests works over a network connection. The first step in getting a resource from a server is to connect to that server. Establishing a connection with a remote server may take some time, depending on network speed, network latency, and server load. Curl has default timeouts for connection and total request time, but we can specify our timeouts for each Curl command.

How to set a timeout for a Curl command?

To set a timeout for a Curl command, you can use the --connect-timeout parameter to set the maximum time in seconds that you allow Curl to connect to the server, or the --max-time (or -m) parameter for the total time in seconds that you authorize the whole operation.

What is --connect-timeout and how to use it?

The –connect-timeout parameter limits the amount of time Curl will spend trying to connect to the remote host. The connection timeout value is specified in seconds. If Curl cannot establish a connection within the specified interval, the command fails.

Curl –connect-timeout syntax
curl --connect-timeout [SECONDS] [URL]

What is -max-time and how to use it?

The –max-time (or -m) parameter is the maximum time, in seconds, within which the entire operation must completed or be canceled. The --max-time option can prevent Curl from hanging when executing batch jobs on slow networks.

Curl -max-time syntax
curl --max-time [SECONDS] [URL]
curl -m [SECONDS] [URL]

How to set connection timeout for Curl?

In the following example, we set a connection timeout for the Curl command when sending a request to the ReqBin echo URL:

Curl Connection-Timeout Example
curl --connect-timeout 5 https://reqbin.com/echo

How to limit the total time of a Curl command?

In the following example, to limit the total time of the Curl command to ten seconds, we can use the --max-time option:

Curl Max-Time Example
curl --max-time 10 https://reqbin.com/echo

How to use both timeouts in a request?

In the following example, we use both timeouts in the same command:

Curl Timeout Example
curl https://reqbin.com/echo
   --connect-timeout 5
   --max-time 10 

You can use --speed-limit and --speed-time as timeout alternative

You can use the --speed-time and -speed-limit command-line options as an alternative to the fixed timeout. With these parameters, you can tell Curl to cancel a transmission if it falls below a certain speed and stays below that threshold for a certain amount of time. For example, if the baud rate falls below 5000 bytes per second for 15 seconds, Curl will stop this:

Curl Cancel Low-speed Transfers
curl https://reqbin.com/echo
   --speed-limit 5000
   --speed-time 15

What is TCP Timeout?

TCP stands for Transmission Control Protocol. The TCP keepalive timeout specifies the interval during which a TCP connection checks to see if a Fiber Channel over IP (FCIP) link is up. This ensures that a link failure is detected quickly, even if the link is inactive. Curl enables TCP support by default. TCP keepalive is a feature that makes the TCP stack send a probe to the other side when there is no traffic to make sure it is still there and alive. Use --keepalive-time to specify how often you want the probe to be sent to the partner in whole seconds. The default is 60 seconds. Sometimes this probing interferes with what you are doing, and you can easily disable it with --no-keepalive.

Curl Keepalive Timeout Example
curl --keepalive-time 180 https://reqbin.com/echo

Curl Disable Keepalive Example
curl --no-keepalive https://reqbin.com/echo

See also

Generate Code Snippets for Curl Timeout Example

Convert your Curl Timeout request to the PHP, JavaScript/AJAX, Node.js, Curl/Bash, Python, Java, C#/.NET code snippets using the ReqBin code generator.