17 min read

Source: Roblox Creator Hub · CC BY 4.0 · View source · Code samples: MIT Imported 2026-10-03. Formatting adapted for this site.

HttpService

Inherits from: Instance → Object

HttpService allows HTTP requests to be sent from experience servers using RequestAsync, GetAsync and PostAsync. This service allows experiences to be integrated with third-party web services such as analytics, data storage, remote server configuration, error reporting, advanced calculations, or real-time communication. Additionally, it can call a subset of the Open Cloud APIs.

For more information about these use cases, see In-experience HTTP requests.

HttpService also houses the JSONEncode and JSONDecode methods, which are useful for communicating with services that use the JSON format. In addition, the GenerateGUID method provides random 128‑bit labels which can be treated as probabilistically unique in a variety of scenarios.

Within Studio, use CreateWebStreamClient() to process data in real time from servers that support streaming protocols such as SSE, chunked transfer encoding, and WebSockets. You can connect callback functions to stream events, allowing you to process data immediately as it arrives instead of waiting for the entire response to complete.

Only send HTTP requests to trusted third-party platforms to avoid introducing unnecessary security risks to your experience.

Inherits from: Instance

Memory category: Instances

Tags: NotCreatable, Service

Code samples: View on Creator Hub (Astronauts-in-Space, International-Space-Station, HttpService-Pastebin, OpenCloud-via-HttpService).

Properties

Name	Type / Returns	Description
HttpService.HttpEnabled	boolean	Indicates whether HTTP requests can be sent to external websites.

Inherited from Instance

Name	Type / Returns	Description
Instance.Archivable	boolean	Determines if an `Instance` and its descendants can be cloned using `Instance:Clone()`, and can be saved/published.
Instance.archivable	boolean
Instance.Capabilities	SecurityCapabilities	The set of capabilities allowed to be used for scripts inside this container.
Instance.IsInSandbox	boolean	Indicates whether the instance is inside a sandboxed container.
Instance.Name	string	A non-unique identifier of the `Instance`.
Instance.Parent	Instance	Determines the hierarchical parent of the `Instance`.
Instance.PredictionMode	PredictionMode	Reflects the client-side prediction mode applied to the instance under server-authoritative physics.
Instance.RobloxLocked	boolean	A deprecated property that used to protect `CoreGui` objects.
Instance.Sandboxed	boolean	When enabled, the instance can only access abilities in its `Capabilities` list.
Instance.UniqueId	UniqueId	A unique identifier for the instance.

Inherited from Object

Name	Type / Returns	Description
Object.ClassName	string	A read-only string representing the class this `Object` belongs to.
Object.className	string

HttpService.HttpEnabled

When set to true, allows scripts to send requests to websites using HttpService:GetAsync(), HttpService:PostAsync(), and HttpService:RequestAsync().

This property must be toggled on for unpublished experiences by setting this property to true using the Command Bar:

game:GetService("HttpService").HttpEnabled = true

Field	Value
type	boolean
security	{"read":"None","write":"LocalUserSecurity"}
thread safety	ReadSafe
category	Data
serialization	{"can_load":true,"can_save":true}
capabilities	["Network"]

Methods

Name	Type / Returns	Description
HttpService:CreateWebStreamClient	WebStreamClient	Creates a client that opens a persistent connection to stream data.
HttpService:GenerateGUID	string	Generates a UUID/GUID random string, optionally with curly braces.
HttpService:GetAsync	string	Sends an HTTP `GET` request.
HttpService:GetSecret	Secret	Returns a `Secret` from the secrets store.
HttpService:JSONDecode	Variant	Decodes a JSON string into a Luau table.
HttpService:JSONEncode	string	Generate a JSON string from a Luau table.
HttpService:PostAsync	string	Sends an HTTP `POST` request.
HttpService:RequestAsync	Dictionary	Sends an HTTP request using any HTTP method given a dictionary of information.
HttpService:UrlEncode	string	Replaces URL-unsafe characters with '%' and two hexadecimal characters.

Inherited from Instance

Name	Type / Returns	Description
Instance:AddTag	()	Applies a tag to the instance.
Instance:children	Instances	Returns an array of the object's children.
Instance:ClearAllChildren	()	This method destroys all of an instance's children.
Instance:Clone	Instance	Create a copy of an instance and all its descendants, ignoring instances that are not `Archivable`.
Instance:clone	Instance
Instance:Destroy	()	Sets the `Instance.Parent` property to `nil`, locks the `Instance.Parent` property, disconnects all connections, and calls `Destroy()` on all children.
Instance:destroy	()
Instance:FindFirstAncestor	Instance?	Returns the first ancestor of the `Instance` whose `Instance.Name` is equal to the given name.
Instance:FindFirstAncestorOfClass	Instance?	Returns the first ancestor of the `Instance` whose `Object.ClassName` is equal to the given className.
Instance:FindFirstAncestorWhichIsA	Instance?	Returns the first ancestor of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstChild	Instance?	Returns the first child of the `Instance` found with the given name.
Instance:findFirstChild	Instance
Instance:FindFirstChildOfClass	Instance?	Returns the first child of the `Instance` whose `ClassName` is equal to the given class name.
Instance:FindFirstChildWhichIsA	Instance?	Returns the first child of the `Instance` for whom `Object:IsA()` returns true for the given className.
Instance:FindFirstDescendant	Instance?	Returns the first descendant found with the given `Instance.Name`.
Instance:GetActor	Actor?	Returns the `Actor` associated with the Instance, if any.
Instance:GetAttribute	Variant	Returns the value which has been assigned to the given attribute name.
Instance:GetAttributeChangedSignal	RBXScriptSignal	Returns an event that fires when the given attribute changes.
Instance:GetAttributes	Dictionary	Returns a dictionary of the instance's attributes.
Instance:GetChildren	Instances	Returns an array containing all of the instance's children.
Instance:getChildren	Instances
Instance:GetDebugId	string	Returns a coded string of the debug ID used internally by Roblox.
Instance:GetDescendants	Instances	Returns an array containing all of the descendants of the instance.
Instance:GetFullName	string	Returns a string describing the instance's ancestry.
Instance:GetStyled	Variant	Returns the styled or explicitly modified value of the specified property, or else the default property value if it hasn't been styled/modified.
Instance:GetStyledPropertyChangedSignal	RBXScriptSignal	Returns an event that fires when the given style property changes on the instance.
Instance:GetTags	Array	Gets an array of all tags applied to the instance.
Instance:HasTag	boolean	Check whether the instance has a given tag.
Instance:IsAncestorOf	boolean	Returns true if an `Instance` is an ancestor of the given descendant.
Instance:IsDescendantOf	boolean	Returns `true` if an `Instance` is a descendant of the given ancestor.
Instance:isDescendantOf	boolean
Instance:IsPropertyModified	boolean	Returns `true` if the value stored in the specified property is not equal to the code-instantiated default.
Instance:QueryDescendants	Instances	Returns an array containing all descendants of the instance that match the `selector` string.
Instance:Remove	()	Sets the object's `Parent` to `nil`, and does the same for all its descendants.
Instance:remove	()
Instance:RemoveTag	()	Removes a tag from the instance.
Instance:ResetPropertyToDefault	()	Resets a property to its default value.
Instance:SetAttribute	()	Sets the attribute with the given name to the given value.
Instance:WaitForChild	Instance	Returns the child of the `Instance` with the given name. If the child does not exist, it will yield the current thread until it does.

Inherited from Object

Name	Type / Returns	Description
Object:GetPropertyChangedSignal	RBXScriptSignal	Get an event that fires when a given property of the object changes.
Object:IsA	boolean	Returns true if an object's class matches or inherits from a given class.
Object:isA	boolean

HttpService:CreateWebStreamClient

This method creates a client that establishes a long-lived connection to servers utilizing various streaming technologies, such as Server-Sent Events (SSE). After the connection is established, the client fires signals that you can connect callback functions to with RBXScriptConnection. Use these callbacks to process messages as soon as they arrive, as well as respond to open, close, and error events.

There is a limit of four total clients allowed at one time. Close streams that you no longer need with WebStreamClient:Close(). When the stream is no longer needed, you should disconnect any associated RBXScriptConnections to avoid memory leaks.

This method is available in Studio only. If you use it inside scripts, make sure to remove any references before publishing the experience. We encourage you to create plugins with this feature for reusability and ease of use.

Parameters

Name	Type	Default	Description
streamClientType	WebStreamClientType		The type of streaming connection to intiialize the client with.
requestOptions	Dictionary		A dictionary containing information to be requested from the server. It is identical to `requestOptions` in `HttpService:RequestAsync()`.

Returns

Type	Description
WebStreamClient	A stateful client that emits events in the stream lifecycle.

Field	Value
security	None
thread safety	Unsafe
capabilities	["Network"]

Code samples: View on Creator Hub (HttpService-CreateSSEWebStreamClient, HttpService-CreateRawStreamWebStreamClient).

HttpService:GenerateGUID

This method generates a random universally unique identifier (UUID) string. The sixteen octets of a UUID are represented as 32 hexadecimal (base 16) digits, displayed in five groups separated by hyphens in the form 8-4-4-4-12 for a total of 36 characters, for example 123e4567-e89b-12d3-a456-426655440000.

The UUID specification used is Version 4 (random), variant 1 (DCE 1.1, ISO/IEC 11578:1996). UUIDs of this version are the most commonly used due to their simplicity, as they are entirely randomly generated. Note that this version does not have certain features that other UUID versions have, such as encoded timestamps, MAC addresses, or time-based sorting like UUIDv7 or ULID.

There are over 5.3×10³⁶ unique v4 UUIDs, in which the probability of finding a duplicate within 103 trillion UUIDs is one in a billion.

The wrapInCurlyBraces argument determines whether the returned string is wrapped in curly braces ({}). For instance:

true: {94b717b2-d54f-4340-a504-bd809ef5bf5c}
false: db454790-7563-44ed-ab4b-397ff5df737b

This method can be used regardless of whether HTTP requests are enabled.

Parameters

Name	Type	Default	Description
wrapInCurlyBraces	boolean	true	Whether the returned string should be wrapped in curly braces (`{}`).

Returns

Type	Description
string	The randomly generated UUID.

Field	Value
security	None
thread safety	Safe

Code samples: View on Creator Hub (HttpService-GenerateGUID).

HttpService:GetAsync

This method sends an HTTP GET request. It functions similarly to RequestAsync() except that it accepts HTTP request parameters as method parameters instead of a single dictionary and returns only the body of the HTTP response. Generally, this method is useful only as a shorthand and RequestAsync() should be used in most cases.

When true, the nocache parameter prevents this method from caching results from previous calls with the same url.

The url parameter also accepts a Secret value; use GetSecret combined with AddPrefix and AddSuffix to safely embed secret credentials (such as API keys) directly in the URL without exposing their values.

Parameters

Name	Type	Default	Description
url	Variant		The web address you are requesting data from.
nocache	boolean	false	Whether the request stores (caches) the response.
headers	Variant		Used to specify some HTTP request headers.

Returns

Type	Description
string	The GET request's response body.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Network"]

Code samples: View on Creator Hub (Astronauts-in-Space, International-Space-Station).

HttpService:GetSecret

This method returns a value previously added to the secrets store for the experience. The secret content is not printable and not available when the experience runs locally.

The returned Secret can be transformed using built-in methods such as Secret:AddPrefix(). It is expected to be sent as a part of an HTTP request.

For more information, see the usage guide.

Parameters

Name	Type	Default	Description
key	string		The name of the secret to fetch, matching the identifier under which it was added to the experience's secrets store.

Returns

Type	Description
Secret	A `Secret` wrapping the stored value associated with `key`.

Field	Value
security	None
thread safety	Safe
capabilities	["Network"]

HttpService:JSONDecode

This method transforms a JSON object or array into a Luau table with the following characteristics:

Keys of the table are strings or numbers but not both. If a JSON object contains both, string keys are ignored.
An empty JSON object generates an empty Luau table ({}).
If the input string is not a valid JSON object, this method will throw an error.

To encode a Luau table into a JSON object, use the HttpService:JSONEncode() method.

This method can be used regardless of whether HTTP requests are enabled.

Parameters

Name	Type	Default	Description
input	string		The JSON object being decoded.

Returns

Type	Description
Variant	The decoded JSON object as a Luau table.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe

Code samples: View on Creator Hub (HttpService-JSONDecode).

HttpService:JSONEncode

This method transforms a Luau table into a JSON object or array based on the following guidelines:

Keys of the table must be either strings or numbers. If a table contains both, an array takes priority (string keys are ignored).
An empty Luau table ({}) generates an empty JSON array (e.g. []).
Whether passing a dictionary table or a numerically indexed table, avoid nil values for any index.
Cyclic table references cause an error.

This method allows values such as inf and nan which are not valid JSON. This may cause problems if you want to use the outputted JSON elsewhere.

This method also accepts buffers up to 50 MiB, which it encodes to base64 (and often compresses) before converting to a JSON object.

To reverse the encoding process and decode a JSON object, use the HttpService:JSONDecode() method.

This method can be used regardless of whether HTTP requests are enabled.

Parameters

Name	Type	Default	Description
input	Variant		The input Luau table.

Returns

Type	Description
string	The returned JSON string.

Field	Value
tags	["CustomLuaState"]
security	None
thread safety	Safe

Code samples: View on Creator Hub (HttpService-JSONEncode).

HttpService:PostAsync

This method sends an HTTP POST request. It functions similarly to RequestAsync() except that it accepts HTTP request parameters as method parameters instead of a single dictionary and returns only the body of the HTTP response. Generally, this method is useful only as a shorthand and RequestAsync() should be used in most cases.

When true, the compress parameter controls whether a large request body is compressed using gzip.

The url parameter also accepts a Secret value — use GetSecret combined with AddPrefix and AddSuffixto safely embed secret credentials (such as API keys) directly in the URL without exposing their values.

Parameters

Name	Type	Default	Description
url	Variant		The destination address for the data.
data	string		The data being sent.
content_type	HttpContentType	ApplicationJson	Modifies the value in the `Content-Type` header sent with the request.
compress	boolean	false	Determines whether the data is compressed (gzipped) when sent.
headers	Variant		Used to specify some HTTP request headers.

Returns

Type	Description
string	The HTTP response sent back indicating the request result.

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Network"]

Code samples: View on Creator Hub (HttpService-Pastebin).

HttpService:RequestAsync

This method 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. Optionally, the request can be compressed using HttpCompression.

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.
`Compress`	`Enum.HttpCompression`	no	An optional compression field that will compress the data in the request. The value can either be `Enum.HttpCompression.None` or `Enum.HttpCompression.Gzip`.
`Timeout`	Integer	no	An optional timeout value in seconds to make requests time out more quickly. Values must be greater than zero and no greater than the default request timeout. This can be useful when debugging hanging requests.

Supported HTTP methods

The HTTP request methods specify the purpose of the request being made and what is expected if the request is successful. For instance, the GET request method tells the server at the requested address that a resource is being requested and, if it succeeds, the resource at that address will be returned. Similarly, the HEAD request method does the same except the server knows to return a response without a Body element.

Method	Description	Safe
`GET` ⓘ	The `GET` method requests the resource at the specified address. Does not support use of the `Body` parameter.	Yes
`HEAD` ⓘ	The `HEAD` method requests a response identical to a `GET` request, but with no response body. Does not support use of the `Body` parameter.	Yes
`POST` ⓘ	The `POST` method submits the supplied `Body` data to the requested address.	No
`PUT` ⓘ	The `PUT` method replaces all current iterations of the resource specified within the supplied `Body` data.	No
`DELETE` ⓘ	The `DELETE` method deletes the resource specified in the supplied `Body` data at the requested address.	No
`OPTIONS` ⓘ	The `OPTIONS` method requests the permitted communication options for the supplied address.	Yes
`TRACE` ⓘ	The `TRACE` method performs a message loop-back test along the path to the resource specified in the supplied `Body` data.	Yes
`PATCH` ⓘ	The `PATCH` method applies partial changes to the resource specified in the supplied `Body` data at the requested address.	No

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.

The RequestAsync() 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 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

RequestAsync() 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

RequestAsync() 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 LuaGlobals.pcall() and gracefully handle failure cases if the required information isn't available.

Limitations

The current limitation for sending and receiving external HTTP requests is 500 requests per minute. There is also a separate limit of 2500 requests per minute for Open Cloud requests. Requests over these thresholds will fail.

Parameters

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

Returns

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

Field	Value
tags	["Yields"]
security	None
thread safety	Unsafe
capabilities	["Network"]

Code samples: View on Creator Hub (sending-an-http-request, OpenCloud-via-HttpService).

HttpService:UrlEncode

This method percent-encodes a given string so that reserved characters properly encoded with % and two hexadecimal characters.

This is useful when formatting URLs for use with HttpService:GetAsync()/HttpService:PostAsync(), or POST data of the media type application/x-www-form-urlencoded (Enum.HttpContentType.ApplicationUrlEncoded).

For instance, when you encode the URL https://www.roblox.com/discover#/, this method returns https%3A%2F%2Fwww%2Eroblox%2Ecom%2Fdiscover%23%2F.

Parameters

Name	Type	Default	Description
input	string		The string (URL) to encode.

Returns

Type	Description
string	The encoded string.

Field	Value
security	None
thread safety	Safe
capabilities	["Network"]

Code samples: View on Creator Hub (HttpService-UrlEncode, HttpService-Pastebin).

Events

Inherited from Instance

Name	Type / Returns	Description
Instance.AncestryChanged		Fires when the `Instance.Parent` property of this object or one of its ancestors is changed.
Instance.AttributeChanged		Fires whenever an attribute is changed on the `Instance`.
Instance.ChildAdded		Fires after an object is parented to this `Instance`.
Instance.childAdded
Instance.ChildRemoved		Fires after a child is removed from this `Instance`.
Instance.DescendantAdded		Fires after a descendant is added to the `Instance`.
Instance.DescendantRemoving		Fires immediately before a descendant of the `Instance` is removed.
Instance.Destroying		Fires immediately before (or is deferred until after) the instance is destroyed via `Instance:Destroy()`.
Instance.StyledPropertiesChanged		Fires whenever any style property is changed on the instance, including when a property is set to `nil`.

Inherited from Object

Name	Type / Returns	Description
Object.Changed		Fires immediately after a property of the object changes, with some limitations.