User

This reference documents APIs relating to users. It exposes endpoints for both the authenticated user only (asset uploading, experience following, etc), and all users on Roblox (inventory, headshots, user info, etc).

rblxopencloud.User(id, api_key)

Bases: Creator

Represents a user on Roblox. It is used to provide information about a user in OAuth2, and to upload assets to a user.

Parameters:

Name	Type	Description	Default
id	int	The user's ID.	required
api_key	str	Your API key created from Creator Dashboard with access to this user.	required

Attributes:

Name	Type	Description
id	int	The user's ID.
username	Optional[str]	The user's username
name	Optional[str]	An alias for username.
display_name	Optional[str]	The non-unqiue display name for the user.
profile_uri	Optional[str]	A URI to the user's rendered profile.
headshot_uri	Optional[str]	For AccessToken, a URI to the user's Roblox avatar profile picture. For other purposes, see generate_headshot.
created_at	Optional[datetime]	The timestamp the user's account was created at.
about	Optional[str]	The user's about me description.
locale	Optional[str]	The user's currently selected IETF language code.
premium	Optional[bool]	Whether the user has Roblox premium.
id_verified	Optional[bool]	Whether the user has verified a non-VOIP phone number or governement ID. Requires the scope user.advanced:read.
social_links	Optional[UserSocialLinks]	The user's social links. Requires the scope user.social:read.
verified	Optional[bool]	Whether the user has a verified badge. This is not populated by fetch_info(), but is populated for users returned by the group audit logs and toolbox endpoints.

fetch_asset(asset_id)

Fetches an asset uploaded to Roblox.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to fetch.	required

Returns:

Type	Description
Asset	An Asset representing the asset.

upload_asset(file, asset_type, name, description, expected_robux_price=0, asset_privacy=AssetPrivacy.Default)

Uploads the file to Roblox as an asset and returns an Operation. The following asset types are currently supported:

Asset Type	File Formats
Decal	.png, .jpeg, .bmp, .tga
Audio	.mp3, .ogg, .wav, .flac
Model	.fbx, .gltf, .glb, .rbxm, .rbxmx
Video	.mp4, .mov
Animation	.rbxm, .rbxmx

According to Roblox staff in this DevForum post, the maximum file size using the API is 30MB.

Parameters:

Name	Type	Description	Default
file	BytesIO	The file opened in bytes to be uploaded.	required
asset_type	Union[AssetType, str]	The AssetType for the asset type you're uploading.	required
name	str	The name of your asset.	required
description	str	The description of your asset.	required
expected_robux_price	int	The amount of robux expected to upload this asset. Will fail if lower than the actual price.	0
asset_privacy	AssetPrivacy	Whether the asset is restricted or open use.	Default

Returns:

Type	Description
Operation[Asset]	Returns a Operation for the asset upload operation where T is an Asset.

Danger

Avoid uploading assets to Roblox that you don't have full control over, such as AI generated assets or content created by unknown people. Assets uploaded that break Roblox's Terms of Services can get your account moderated.

For OAuth2 developers, it has been confirmed by Roblox staff in this DevForum post, that your app will not be punished if a malicious user uses it to upload Terms of Service violating content, and instead the authorizing user's account will be punished.

update_asset(asset_id, file=None, name=None, description=None, expected_robux_price=0, facebook_social_link=None, twitter_social_link=None, youtube_social_link=None, twitch_social_link=None, discord_social_link=None, github_social_link=None, roblox_social_link=None, guilded_social_link=None, devforum_social_link=None, try_place_id=None)

Updates an asset on Roblox with the provided file. The following asset types are currently supported for file uploading:

Asset Type	File Formats
Model	.fbx

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to update.	required
file	BytesIO	The file opened in bytes to upload. The asset must be one of the supported file formats above.	None
name	str	The new name of the asset.	None
description	str	The new description for the asset.	None
expected_robux_price	int	The amount of robux expected to update this asset. Will fail if lower than the actual price.	0
facebook_social_link	Optional[Union[AssetSocialLink, None]]	The new Facebook social link for the asset, or False to remove the social link.	None
twitter_social_link	Optional[Union[AssetSocialLink, None]]	The new Twitter social link for the asset, or False to remove the social link.	None
youtube_social_link	Optional[Union[AssetSocialLink, None]]	The new YouTube social link for the asset, or False to remove the social link.	None
twitch_social_link	Optional[Union[AssetSocialLink, None]]	The new Twitch social link for the asset, or False to remove the social link.	None
discord_social_link	Optional[Union[AssetSocialLink, None]]	The new Discord social link for the asset, or False to remove the social link.	None
github_social_link	Optional[Union[AssetSocialLink, None]]	The new GitHub social link for the asset, or False to remove the social link.	None
roblox_social_link	Optional[Union[AssetSocialLink, None]]	The new Roblox social link for the asset, or False to remove the social link.	None
guilded_social_link	Optional[Union[AssetSocialLink, None]]	The new Guilded social link for the asset, or False to remove the social link.	None
devforum_social_link	Optional[Union[AssetSocialLink, None]]	The new DevForum social link for the asset, or False to remove the social link.	None
try_place_id	Optional[Union[int, bool]]	A place ID to set for the asset's 'Try in Roblox' button. Set to False to remove the Try in Roblox button.	None

Returns:

Type	Description
Operation[Asset]	Returns a Operation for the asset update operation where T is an Asset.

list_asset_versions(asset_id, limit=None)

Iterates all avaliable versions of the asset, providing the latest version first.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to find versions for.	required
limit	int	The maximum number of versions to return.	None

Yields:

Type	Description
Iterable[AssetVersion]	An asset version for each version of the asset.

fetch_asset_version(asset_id, version_number)

Fetches the version for a specific version number of the asset.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to find the version for.	required
version_number	int	The version number to find.	required

Returns:

Type	Description
AssetVersion	The found asset version.

rollback_asset(asset_id, version_number)

Reverts the asset to a previous version specified.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to rollback.	required
version_number	int	The version number to rollback to.	required

Returns:

Type	Description
AssetVersion	The new asset version.

archive_asset(asset_id)

Archives the asset so it cannot be seen on the website or used in experiences.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to archive.	required

Returns:

Type	Description
Asset	The updated asset information.

restore_asset(asset_id)

Unarchives an archived asset.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the archived asset to unarchive.	required

Returns:

Type	Description
Asset	The updated asset information.

fetch_asset_delivery_location(asset_id, version_number=None, expected_asset_type=None)

Fetches the download location for this asset using Asset Delivery.

Requires the legacy-assets:manage API key permission.

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to fetch the location for.	required
version_number	Optional[int]	The specific version number of the asset to fetch the location for. Defaults to the latest version.	None
expected_asset_type	Optional[Union[AssetType, str]]	The expected type of the asset. If provided, the request will fail if the asset is not of the provided type.	None

Returns:

Type	Description
AssetDeliveryLocation	An AssetDeliveryLocation containing information on downloading the asset.

fetch_creator_store_product(asset_type, product_id)

Fetches information about an asset on the creator store.

Parameters:

Name	Type	Description	Default
asset_type	Union[AssetType, str]	The type of asset the product is.	required
product_id	int	The ID of the asset to fetch.	required

Returns:

Type	Description
CreatorStoreProduct	A CreatorStoreProduct representing the asset.

Tip

If the asset type is unknown or other information such as the description is required, use the fetch_asset.

fetch_toolbox_asset(asset_id)

Fetches information about an asset in the toolbox.

Requires creator-store-product:read on an API key. OAuth2 authorization is not supported. No authorization is supported (i.e. api_key is None).

Parameters:

Name	Type	Description	Default
asset_id	int	The ID of the asset to fetch.	required

Returns:

Type	Description
ToolboxAsset	The asset information for the toolbox asset. The current creator object (e.g. user or group) will also be updated with resolved information such as name and verified status.

Tip

To search for assets in the toolbox, use ApiKey.search_toolbox.

grant_assets_permission(action, subject, assets)

Grants permission to the subject to perform the specified action on the provided assets. See the table in AssetPermissionAction for allowed actions per asset and subject type.

Parameters:

Name	Type	Description	Default
action	AssetPermissionAction	The action to grant permission for.	required
subject	Union[AssetPermissionSubject, Experience, User, Group, GroupRole]	The subject to grant the permission to.	required
assets	list[Union[int, Asset, AssetPermissionRequest]]	The asset IDs or assets to grant permission for. Use AssetPermissionRequest to specify additional options per asset.	required

Returns:

Type	Description
AssetPermissionResult	The results of each asset permission grant request. Do not expect the function to raise an exceptions for errors, instead check the failed_asset_ids attribute.

Warning

Once permission is granted to a subject, it cannot be revoked using the API. It may also not be able to be revoked using the website, depending on the asset type and subject type. For instance, granting Open Use to All on a decal sets it as Open Use which cannot be revoked; however, granting Download to All on a place can be revoked on the Creator Dashboard.

Example

Setting the root place of an experience to be uncopylocked.

from rblxopencloud import Experience, AssetPermissionAction,             AssetPermissionSubject, AssetPermissionSubjectType

experience = Experience(00000000, "...") # initialise with ID and API key
experience.fetch_info() # Fetch root place

# grant download permission to everyone on Roblox
experience.creator.grant_assets_permission(
    action=AssetPermissionAction.Download,
    subject=AssetPermissionSubject(
        type=AssetPermissionSubjectType.All
    ),
    assets=[experience.root_place.get_asset()]
)
>>> <rblxopencloud.AssetPermissionResult granted_asset_ids=[00000000] failed_asset_ids={}>

Setting an asset to be Open Use.

from rblxopencloud import User, AssetPermissionAction,             AssetPermissionSubject, AssetPermissionSubjectType,             AssetPermissionRequest

creator = User(00000000, "...") # initialise with user ID and API key

creator.grant_assets_permission(
    action=AssetPermissionAction.Use,
    subject=AssetPermissionSubject(
        type=AssetPermissionSubjectType.All
    ),
    assets=[
        AssetPermissionRequest(
            asset_id=00000000, # ID of the asset to grant permission for
            grant_dependencies=True
        )
    ]
)
>>> <rblxopencloud.AssetPermissionResult granted_asset_ids=[00000000] failed_asset_ids={}>

Granting a specific user permission to use an asset.

from rblxopencloud import User, AssetPermissionAction,             AssetPermissionSubject, AssetPermissionSubjectType,             AssetPermissionRequest

creator = User(00000000, "...") # initialise with user ID and API key

creator.grant_assets_permission(
    action=AssetPermissionAction.Use,
    subject=AssetPermissionSubject( # subject can also be a User or Group object
        type=AssetPermissionSubjectType.User,
        id=00000000 # ID of the user to grant permission to
    ),
    assets=[
        AssetPermissionRequest(
            asset_id=00000000, # ID of the asset to grant permission for
            grant_dependencies=True
        )
    ]
)
>>> <rblxopencloud.AssetPermissionResult granted_asset_ids=[00000000] failed_asset_ids={}>

fetch_info()

Updates the empty attributes in the class with the user info.

Returns:

Type	Description
User	The class itself.

generate_headshot(size=420, format='png', is_circular=False)

Fetches the user's thumbnail from Roblox and returns an Operation.

Parameters:

Name	Type	Description	Default
size	Literal[48, 50, 60, 75, 100, 110, 150, 180, 352, 420, 720]	The size in pixels of the generated headshot. Must be one of: 48, 50, 60, 75, 100, 110, 150, 180, 352, 420 or 720.	420
format	Literal['png', 'jpeg']	The file format of the generated image.	'png'
is_circular	bool	Wether the generated thumbnail has a circular cut out.	False

Returns:

Type	Description
Operation[str]	The Operation to get the thumbnail. In most cases, the final result will be cached and returned immediately from Operation.wait.

fetch_managing_groups()

Fetches the groups that the authenticated user can manage.

Requires legacy-group:manage on an API Key or OAuth2 authorization.

Returns:

Type	Description
list[Group]	A list of groups that the authenticated user can manage with name and id resolved.

Legacy API

This endpoint uses the legacy Develop API. Roblox has noted in this DevForum post that these endpoints may change without notice and break your application. Therefore, they should be used with caution.

Please report issues with this endpoint on the GitHub issue tracker or the Discord server.

Warning

Irrespective of requested user, this will always return the groups that the authenticated user can manage (e.g. ApiKey.authorized_user).

list_groups(limit=None)

Iterates a GroupMember for every group the user is in. Use GroupMember.group to get the group.

Parameters:

Name	Type	Description	Default
limit	int	The max number of groups to iterate.	None

Yields:

Type	Description
Iterable[GroupMember]	GroupMember for every group the user is in.

list_inventory(limit=None, only_collectibles=False, assets=None, badges=False, game_passes=False, private_servers=False)

Iterates InventoryItem for items in the user's inventory. If only_collectibles, assets, badges, game_passes, and private_servers are False, then all inventory items are returned.

Parameters:

Name	Type	Description	Default
limit	Optional[int]	The maximum number of inventory items to iterate. This can be None to return all items.	None
only_collectibles	bool	Whether the only inventory assets returned are collectibles (limited items).	False
assets	Optional[Union[list[InventoryAssetType], list[int], bool]]	If True, then it will return all assets, if it is a list of IDs, it will only return assets with the provided IDs, and if it is a list of InventoryAssetType then it will only return assets of these types.	None
badges	Union[list[int], bool]	If True, then it will return all badges, but if it is a list of IDs, it will only return badges with the provided IDs.	False
game_passes	Union[list[int], bool]	If True, then it will return all game passes, but if it is a list of IDs, it will only return game passes with the provided IDs.	False
private_servers	Union[list[int], bool]	If True, then it will return all private servers, but if it is a list of IDs, it will only return private servers with the provided IDs.	False

fetch_experience_followings()

Fetches the list of experiences the user is following.

Requires legacy-universe.following:read on an API Key or OAuth2 authorization. The requested user must be the authenticated user to fetch this information.

Example

Fetches the experiences the user is following and finds the oldest one. The year they followed it is then printed along with the experience name.

followings = user.fetch_experience_followings()
for following in followings:
    if not oldest_follow or following.followed_at < oldest_follow.followed_at:
        oldest_follow = following

oldest_follow.experience.fetch_info()
print(f"The user's oldest experience follow is {oldest_follow.experience.name} since {oldest_follow.followed_at.year}")
>>> "The user's oldest experience follow is Natural Disaster Survival since 2018"

Returns:

Type	Description
list[UserExperienceFollowing]	A list of experiences the user is following, and the time they followed at. can_follow, following_count, and following_limit will all be None.

Legacy API

This endpoint uses the legacy Followings API. Roblox has noted in this DevForum post that these endpoints may change without notice and break your application. Therefore, they should be used with caution.

Please report issues with this endpoint on the GitHub issue tracker or the Discord server.

fetch_experience_following_status(experience_id)

Fetches the following status of the requested experience for the user.

Requires legacy-universe.following:read on an API Key or OAuth2 authorization. The requested user must be the authenticated user to fetch this information.

Parameters:

Name	Type	Description	Default
experience_id	int	The ID of the experience to fetch status for; not to be confused with a place ID.	required

Returns:

Type	Description
UserExperienceFollowing	The following status object with followed_at being None.

Legacy API

This endpoint uses the legacy Followings API. Roblox has noted in this DevForum post that these endpoints may change without notice and break your application. Therefore, they should be used with caution.

Please report issues with this endpoint on the GitHub issue tracker or the Discord server.

follow_experience(experience_id)

Follows the requested experience for the user. This means the user will recieve updates and notifications for the experience.

Requires legacy-universe.following:write on an API Key or OAuth2 authorization. The requested user must be the authenticated user to use this endpoint.

Parameters:

Name	Type	Description	Default
experience_id	int	The ID of the experience to follow; not to be confused with a place ID.	required

Legacy API

This endpoint uses the legacy Followings API. Roblox has noted in this DevForum post that these endpoints may change without notice and break your application. Therefore, they should be used with caution.

Please report issues with this endpoint on the GitHub issue tracker or the Discord server.

unfollow_experience(experience_id)

Unfollows the requested experience for the user. This means the user will no longer recieve updates and notifications for the experience.

Requires legacy-universe.following:write on an API Key or OAuth2 authorization. The requested user must be the authenticated user to use this endpoint.

Parameters:

Name	Type	Description	Default
experience_id	int	The ID of the experience to unfollow; not to be confused with a place ID.	required

Legacy API

This endpoint uses the legacy Followings API. Roblox has noted in this DevForum post that these endpoints may change without notice and break your application. Therefore, they should be used with caution.

Please report issues with this endpoint on the GitHub issue tracker or the Discord server.

list_asset_quotas(limit=None, quota_type=None, asset_type=None)

Iterates the user's asset quotas, indicating how many assets can be uploaded or distributed on the creator store for each type over a given time period.

Requires assets:read on an API Key or OAuth2 authorization.

Example

Fetches the asset quota for uploading audio assets. It uses a limit of 1 since there should only be one quota for this type. Due to the API, however, it is still returned as an iterable so it is condensed into a list and the first item is accessed to get the quota information.

quotas = list(
    user.list_asset_quotas(
        quota_type=AssetQuotaType.Upload,
        asset_type=AssetType.Audio,
        limit=1,
    )
)

if quotas and quotas[0].remaining > 0:
    print("You can upload more audio assets!")
elif quotas and quotas[0].resets_at:
    print(f"You cannot upload more audio assets until {quotas[0].resets_at}.")

Parameters:

Name	Type	Description	Default
limit	Optional[int]	The maximum number of asset quotas to iterate. This can be None to return all asset quotas.	None

Yields:

Type	Description
Iterable[AssetQuota]	Asset quota information for each type of asset.

Non-creatable Dataclasses

rblxopencloud.AssetQuota

Represents the quota of an asset type for a user indicating how many assets can be uploaded or distributed on the creator store.

Attributes:

Name	Type	Description
asset_type	AssetType	The type of asset this quota applies to.
quota_type	AssetQuotaType	Whether the quota is for uploading or distributing on the creator store.
capacity	int	The maximum number of assets that can be uploaded or distributed on the creator store in the given period.
usage	int	The number of assets that have been uploaded or distributed on the creator store in the given period.
remaining	int	The number of assets that can still be uploaded or distributed on the creator store in the given period. This is equivalent to capacity - usage.
period	AssetQuotaPeriod	The period for which this quota applies.
resets_at	Optional[datetime]	The time at which this quota will reset. This may be None if none of the limit has been used yet.

rblxopencloud.InventoryAsset

Bases: InventoryItem

Represents an asset in a user's inventory such as clothing and development items.

Attributes:

Name	Type	Description
id	int	The ID of the asset.
added_at	Optional[datetime]	The time the asset was added to the inventory.
type	InventoryAssetType	The asset's type.
instance_id	int	The unique ID of this asset's instance.
collectable_item_id	Optional[str]	A unique item UUID for collectables.
collectable_instance_id	Optional[str]	A unique instance UUID for collectables.
serial_number	Optional[int]	The serial number of the collectable.
collectable_state	Optional[InventoryItemState]	Wether the item is ready for sale or in hold.

rblxopencloud.InventoryBadge

Bases: InventoryItem

Represents a badge in a user's inventory.

Attributes:

Name	Type	Description
id	int	The ID of the badge.
added_at	Optional[datetime]	The time the badge was awarded.

rblxopencloud.InventoryGamePass

Bases: InventoryItem

Represents a game pass in a user's inventory.

Attributes:

Name	Type	Description
id	int	The ID of the game pass.

rblxopencloud.InventoryItem

Represents an asset, badge, or gamepass in the user's inventory.

Attributes:

Name	Type	Description
id	int	The ID of the inventory item.
added_at	Optional[datetime]	The time the item was added to the inventory. Currently not present for game passes.

rblxopencloud.InventoryPrivateServer

Bases: InventoryItem

Represents a game pass in a user's inventory.

Attributes:

Name	Type	Description
id	int	The ID of the private server.
added_at	Optional[datetime]	The time the private server was purchased.

rblxopencloud.UserExperienceFollowing

Data class storing information about an experience followed by a user.

Attributes:

Name	Type	Description
is_following	bool	Whether the experience is followed.
experience	Experience	The experience that has been followed.
followed_at	Optional[datetime]	The time that the user followed the experience. Only present for when returned by fetch_experience_followings()
can_follow	Optional[bool]	Whether the user can follow this experience. Only present for when returned by fetch_experience_following_status()
following_count	Optional[int]	The number of experiences the user is following fetch_experience_following_status()
following_limit	Optional[int]	The maximum number of experiences the user can follow. Only present for when returned by fetch_experience_following_status()

rblxopencloud.UserSocialLinks

Data class storing information about a user's social links.

Attributes:

Name	Type	Description
facebook_uri	str	Facebook profile URI, empty string if not provided.
guilded_uri	str	Guilded profile URI, empty string if not provided.
twitch_uri	str	Twitch profile URI, empty string if not provided.
twitter_uri	str	Twitter profile URI, empty string if not provided.
youtube_uri	str	YouTube profile URI, empty string if not provided.
visibility	UserVisibility	The visiblity of these social links to user's on the platform.

Enums

rblxopencloud.AssetQuotaPeriod

Bases: Enum

Enum denoting the period of an asset quota.

Attributes:

Name	Type	Description
Unknown	0	An unknown, unspecified, or unspecified quota period.
Day	1	The quota resets daily.
Month	2	The quota resets monthly.

rblxopencloud.AssetQuotaType

Bases: Enum

Enum denoting the type of an asset quota.

Attributes:

Name	Type	Description
Unknown	0	An unknown, unspecified, or unspecified quota type.
Upload	1	The quota is a ratelimit for uploading assets.
CreatorStoreDistribution	2	The quota is a ratelimit for distributing assets on the creator store.

rblxopencloud.InventoryItemState

Bases: Enum

Enum representing whether a collectable InventoryAsset can be traded/ sold or is currently on hold.

Attributes:

Name	Type	Description
Unknown	0	The status is unknown.
Available	1	The collectable can be traded and sold.
Hold	2	The collectable cannot be traded or sold yet.

rblxopencloud.InventoryAssetType

Bases: Enum

Enum representing the type of an InventoryAsset.

Attributes:

Name	Type	Description
Unknown(0)		The asset type is unknown/unsupported.
ClassicTShirt(1)
Audio(2)
Hat(3)
Model(4)
ClassicShirt(5)
ClassicPants(6)
Decal(7)
ClassicHead(8)
Face(9)
Gear(10)
Animation(11)
Torso(12)
RightArm(13)
LeftArm(14)
LeftLeg(15)
RightLeg(16)
Package(17)
Plugin(18)
MeshPart(19)
HairAccessory(20)
FaceAccessory(21)
NeckAccessory(22)
ShoulderAccessory(23)
FrontAccessory(24)
BackAccessory(25)
WaistAccessory(26)
ClimbAnimation(27)
DeathAnimation(28)
FallAnimation(29)
IdleAnimation(30)
JumpAnimation(31)
RunAnimation(32)
SwimAnimation(33)
WalkAnimation(34)
PoseAnimation(35)
EmoteAnimation(36)
Video(37)
TShirtAccessory(38)
ShirtAccessory(39)
PantsAccessory(40)
JacketAccessory(41)
SweaterAccessory(42)
ShortsAccessory(43)
LeftShoeAccessory(44)
RightShoeAccessory(45)
DressSkirtAccessory(46)
EyebrowAccessory(47)
EyelashAccessory(48)
MoodAnimation(49)
DynamicHead(50)
CreatedPlace(51)
PurchasedPlace(52)

rblxopencloud.UserVisibility

Bases: Enum

Enum denoting what visibility a resource has. Currently only applies to social links.

Attributes:

Name	Type	Description
Unknown	0	The visiblity type is unknown
Noone	1	It is visible to no one.
Friends	2	It is visible to only the user's friends.
Following	3	It is visible to the user's friends and users they follow.
Followers	4	It is visible to the user's friends, users they follow, and users that follow them.
Everyone	5	It is visible to everyone.