RequestAsync

Yields

This is a yielding function. When called, it will pause the Lua thread that called the function until a result is ready to be returned, without interrupting other scripts.

Unsafe

For thread safety, this property is not safe to read in an unsynchronized thread.

Function of:

HttpService

Description:

The RequestAsync() function sends an HTTP request using a dictionary to specify the request data, such as the target URL, method, headers and request body data. It returns a dictionary that describes the response data received.

Request Dictionary Fields

Name	Type	Required	Description
Url	String	yes	The target URL for this request. Must use `http` or `https` protocols.
Method	String	no	The HTTP method being used by this request, most often GET or POST.
Headers	Dictionary	no	A dictionary of headers to be used with this request. Most HTTP headers are accepted here, but not all.
Body	String	no	The request body. Can be any string, including binary data. Must be excluded when using the GET or HEAD HTTP methods. It might be necessary to specify the `Content-Type` header when sending JSON or other formats.

HTTP Headers

In the request dictionary, you can specify custom HTTP headers to use in the request. However, some headers cannot be specified. For example, Content-Length is determined from the request body. User-Agent and Roblox-Id are locked by Roblox. Other headers like Accept or Cache-Control use default values but can be overridden. More commonly, some REST APIs may require API keys or other service authentication to be specified in request headers.

This method does not detect the format of body content. Many web servers require the Content-Type header be set appropriately when sending certain formats. Other methods of HttpService use the Enum/HttpContentType|HttpContentType enum; for this method set the Content-Type header appropriately: text/plain, text/xml, application/xml, application/json or application/x-www-form-urlencoded are replacement Content-Type header values for the respective enum values.

Response Dictionary Fields

The function returns a dictionary containing the following fields:

Name	Type	Description
Success	Boolean	The success status of the request. This is true if and only if the StatusCode lies within the range [200, 299].
StatusCode	Integer	The HTTP response code identifying the status of the response.
StatusMessage	String	The status message that was sent back.
Headers	Dictionary	A dictionary of headers that were set in this response.
Body		The request body (content) received in the response.

Error Cases

This method raises an error if the response times out or if the target server rejects the request. If a web service goes down for some reason, it can cause scripts that use this method to stop functioning altogether. It is often a good idea to wrap calls to this method in pcall and gracefully handle failure cases if the required information isn’t available.

Limitations

The current limitation for sending and receiving HTTP requests is 500 requests per minute. Requests over this threshold will fail. Additionally, Roblox domains are blacklisted. This means that HTTP requests cannot be sent to any Roblox owned site, such as www.roblox.com.

Parameters

Name	Type	Default	Description
Name requestOptions	Type Dictionary	Default	Summary A dictionary containing information to be requested from the server specified.

Returns

Return Type	Summary
Return Type Dictionary	Summary A dictionary containing response information from the server specified.

Code Samples

Sending an HTTP Request

This code sample demonstrates sending a single HTTP POST request with JSON data to the website httpbin.org, a website that helps debug HTTP requests. Here, we send some JSON data by using HttpService/JSONEncode and also setting the Content-Type header.

			
				Sending an HTTP Request

				Expected Output
			
				Expand
				
			-- Remember to set enable HTTP Requests in game settings!
local HttpService = game:GetService("HttpService")

local function request()
	local response = HttpService:RequestAsync(
		{
			Url = "http://httpbin.org/post",  -- This website helps debug HTTP requests
			Method = "POST",
			Headers = {
				["Content-Type"] = "application/json"  -- When sending JSON, set this!
			},
			Body = HttpService:JSONEncode({hello = "world"})
		}
	)

	-- Inspect the response table
	if response.Success then
		print("Status code:", response.StatusCode, response.StatusMessage)
		print("Response body:\n", response.Body)
	else
		print("The request failed:", response.StatusCode, response.StatusMessage)
	end
end

-- Remember to wrap the function in a 'pcall' to prevent the script from breaking if the request fails
local success, message = pcall(request)
if not success then
	print("Http Request failed:", message)
end
		
			Status code: 200 OK
Response body:
{"args":{},"data":"{\"hello\":\"world\"}","files":{},"form":{},"headers":{"Accept":"*/*","Accept-Encoding":"gzip, deflate","Cache-Control":"no-cache","Connection":"close","Content-Length":"17","Content-Type":"application/json","Host":"httpbin.org","Roblox-Id":"95206192","User-Agent":"RobloxStudio/WinInet"},"json":{"hello":"world"},"origin":"104.136.21.222","url":"http://httpbin.org/post"}
		
				Copy Code
			
				Light Theme