Skip to main content

Send HEAD request (http.head)

Declaration​

code, res_headers_json = http.head(URL [, timeout_secs, headers, url_no_escape])

Declaration (named arguments)​

Supported since 2025-06-25; progress options are supported since 2026-04-02

code, res_headers_json = http.head{
url = URL;
timeout = timeout_secs;
headers = headers;
params = query_params;
progress = progress_callback;
progress_interval_ms = progress_interval_ms;
}

Parameters​

  • URL
    String. Request URL. The function escapes the URL by default; see "url_no_escape" if you don't want this.
  • timeout_secs
    Number, optional. Timeout in seconds. Default 10.
  • headers
    Table, optional. Request headers in the form { field1 = value1, ... }. Default {}.
  • query_params
    Table, optional. Query string parameters in the form { field1 = value1, ... }. Default {}.
  • progress_callback
    Function, optional. Supported since 2026-04-02. Called when request progress changes. The first argument is the current progress info.
  • progress_interval_ms
    Integer, optional. Supported since 2026-04-02. Progress callback interval in milliseconds.
  • url_no_escape
    Boolean, optional. true = do not escape URL. Default false.
    For custom escaping, see the lcurl module easy:escape and easy:unescape.

Returns​

  • code
    Integer. HTTP status code. -1 on timeout.
  • res_headers_json
    String or nil. Response headers in JSON. nil on timeout.

Description​

Use HTTP/1.1 HEAD method to fetch response headers.
HEAD typically returns the same headers as GET but without body.
This function may yield; other threads may run before it returns.

The info table passed to the progress callback has this structure:

{
count_of_bytes_sent = bytes_sent;
count_of_bytes_expected_to_send = bytes_expected_to_send;
count_of_bytes_received = bytes_received;
count_of_bytes_expected_to_receive = bytes_expected_to_receive;
}

Example​

local c, h = http.head("https://www.xxtouch.app/测试文本.txt")
if c==200 then
sys.alert(h)
end

Note: Uses sys.alert