Send GET request (http.get)

Declaration

status, headersJson, body = http.get(URL [, timeoutSec, headers, URLNoEscape ])

Declaration (named arguments)

Supported since 2025-06-25

status, headersJson, body = http.get{
    url = URL;
    timeout = timeoutSec;
    headers = headers;
    params = queryParams;
    download_file = savePathIfSuccess;
}

Parameters

• URL
  String. Target URL. By default the URL will be percent-escaped; see URLNoEscape if you want to disable escaping.
• timeoutSec
  Number, optional. Timeout in seconds. Default: 10.
• headers
  Table, optional. Request headers as {field1 = value1, ...}. Default: {}.
• queryParams
  Table, optional. Query parameters as {field1 = value1, ...}. Default: {}.
• savePathIfSuccess
  String, optional. If set, the response body will be saved to this file and the body return value will be that path.
• URLNoEscape
  Boolean, optional. true = do not escape URL. Default: false.
  For custom escaping, see lcurl module easy:escape and easy:unescape.

Returns

• status
  Integer. HTTP status code; -1 if timed out.
• headersJson
  String or nil. Response headers in JSON format; nil on timeout.
• body
  String or nil. Response body; or file path if saved to file; nil on timeout.

Notes

Performs an HTTP/1.1 GET request.
This function does not store resources to disk. For large downloads, use http.download.
This function may yield; other threads may run before it returns.
If the server only supports HTTP/1.0 or 0.9, you can use httpGet instead:

body = httpGet(URL, timeoutSec)

Example

local code, res_headers, body = http.get("https://httpbin.org/get?hello=world&你好=世界", 15, {
    ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)"; -- mimic IE8
    ["Cookie"] = "a=1; b=2; c=3"; -- send cookies
})
if code == 200 then
    sys.alert(body)
end

Note: Uses sys.alert

Example (named arguments)

local code, res_headers, body = http.get{
    url = "https://httpbin.org/get";
    timeout = 15;
    headers = {
        ["User-Agent"] = "Mozilla/4.0 (compatible; MSIE 8.0; Windows NT 6.0)";
        ["Cookie"] = "a=1; b=2; c=3";
    };
    params = {
        ["hello"] = "world";
        ["你好"] = "世界";
    };
}
if code == 200 then
    sys.alert(body)
end

Note: Uses sys.alert

Example: get public IP

function get_ip()
    local done = false
    thread.dispatch(function()
        while (true) do
            if (done) then
                sys.toast("", -1)
                return
            else
                sys.toast("Fetching IP...", device.front_orien())
            end
            sys.msleep(2000)
        end
    end)
    while (true) do
        local c, h, b = http.get("https://ip.chinaz.com/?ts="..tostring(sys.rnd()), 60)
        if (c==200) then
            sys.toast("", -1)
            done = true
            return b:match('%d%d?%d?%.%d%d?%d?%.%d%d?%d?%.%d%d?%d?')
        end
    end
end
--
sys.alert(get_ip())

Note: Uses sys.alert, sys.toast, sys.msleep, sys.rnd, thread.dispatch, device.front_orien