Catalog APIs

5 min

Roblox offers formatted catalog item data for use in custom desktop and browser applications.

Avatar Catalog API

Only catalog items from the Avatar Shop can be queried through the following API. Searching for library catalog items (meshes, models, audio, etc.) can be done through the Library Catalog API.

https://catalog.roblox.com/v1/search/items/details?[params]

Query Parameters

Search parameters can be specified by appending a series of parameters and values to the URL, each separated by a &. For example:

https://catalog.roblox.com/v1/search/items/details?Category=3&MaxPrice=1000

Parameter	Type	Options and Values
Category	byte	Featured (=0), All (=1), Collectibles (=2), Clothing (=3), BodyParts (=4), Gear (=5), Accessories (=11), AvatarAnimations (=12), and CommunityCreations (=13).
CreatorName	string	Search by creator name. If CreatorType is not provided, search is for users only.
CreatorTargetId	long	The user or group ID depending on the CreatorType provided.
CreatorType	byte	User (=1) or Group (=2).
Cursor	string	Each search response will contain a nextPageCursor if there is a next page and previousPageCursor if there is a previous page. Pass either of these values in the Cursor parameter of your next query to get the next or previous page of results. The cursor will only be valid if the other query parameters remain the same.
Genres	byte	Specifies the genre for the search. The options are TownAndCity (=1), Medieval (=2), SciFi (=3), Fighting (=4), Horror (=5), Naval (=6), Adventure (=7), Sports (=8), Comedy (=9), Western (=10), Military (=11), Building (=13), FPS (=14), and RPG (=15). The recommended approach to filtering on genres is to match the URL of a catalog page.
Keyword	string	Standard keyword search.
Limit	int	Number of results to return. Values are currently limited to 10, 28, and 30.
MaxPrice	int	The maximum amount of Robux that an item can be priced in the query.
MinPrice	int	The minimum amount of Robux that an item can be priced in the query.
SortAggregation	byte	PastDay (=1), PastWeek (=3), PastMonth (=4), and AllTime (=5).
SortType	byte	Relevance (=0), Favorited (=1), Sales (=2), Updated (=3), PriceAsc (=4), and PriceDesc (=5). Default is Relevance.
Subcategory	byte	Featured (=0), All (=1), Collectibles (=2), Clothing (=3), BodyParts (=4), Gear (=5), Hats (=9), Faces (=10), Shirts (=12), TShirts (=13), Pants (=14), Heads (=15), Accessories (=19), HairAccessories (=20), FaceAccessories (=21), NeckAccessories (=22), ShoulderAccessories (=23), FrontAccessories (=24), BackAccessories (=25), WaistAccessories (=26), AvatarAnimations (=27), Bundles (=37), AnimationBundles (=38), and EmoteAnimations (=39), CommunityCreations (=40), Melee (=41), Ranged (=42), Explosive (=43), PowerUp (=44), Navigation (=45), Musical (=46), Social (=47), Building (=48), and Transport (=49).

Example Search

The following URL will search for the first 10 “Gear” items sorted by all-time (“SortAggregation”) and relevance (“SortType”).

https://catalog.roblox.com/v1/search/items/details?Category=5&Subcategory=5&SortType=0&SortAggregation=5&Limit=10

Response Format

Here’s an example of an item returned in articles/JSON Storage Format|JSON format:

{
	"keyword": null,
	"previousPageCursor": null,
	"nextPageCursor": "2_1_c541d05046b5c1c78a5d386b5e302243",
	"data": [
		{
			"id": 603,
			"itemType": "Bundle",
			"bundleType": 1,
			"name": "Odger Gorm, the Fallen",
			"description": "Once a great warrior, now one of the restless undead.",
			"productId": 945868126,
			"itemStatus": [],
			"itemRestrictions": [
				"Rthro"
			],
			"creatorType": "User",
			"creatorTargetId": 1,
			"creatorName": "ROBLOX",
			"price": 250,
			"purchaseCount": 1191,
			"favoriteCount": 2890
		}
	]
}

Field	Description
assetType	One of the following asset type values (only returned if the item is an asset). `2` = T-Shirt `8` = Hat `11` = Shirt `12` = Pants `17` = Head `18` = Face `19` = Gear `25` = Arms `26` = Legs `27` = Torso `28` = RightArm `29` = LeftArm `30` = LeftLeg `31` = RightLeg `41` = HairAccessory `42` = FaceAccessory `43` = NeckAccessory `44` = ShoulderAccessory `45` = FrontAccessory `46` = BackAccessory `47` = WaistAccessory `48` = ClimbAnimation `49` = DeathAnimation `50` = FallAnimation `51` = IdleAnimation `52` = JumpAnimation `53` = RunAnimation `54` = SwimAnimation `55` = WalkAnimation `56` = PoseAnimation `61` = EmoteAnimation
bundleType	The bundle type ID (only returned if the item is a bundle). Possible values are BodyParts and AvatarAnimations.
creatorName	The creator's name.
creatorTargetId	The creator's ID.
creatorType	The item's creator type.
description	The item description.
favoriteCount	The favorite count of an item.
genres	List of the item's genres. Possible values include All, Tutorial, Scary, TownAndCity, War, Funny, Fantasy, Adventure, SciFi, Pirate, FPS, RPG, Sports, Ninja, and WildWest.
id	The ID of the item.
itemRestrictions	List of the item's restrictions. Possible values include ThirteenPlus, LimitedUnique, Limited, and Rthro.
itemStatus	List of the item's status flags. Possible values include New, Sale, XboxExclusive, AmazonExclusive, GooglePlayExclusive, IosExclusive, and SaleTimer.
itemType	The item type. Possible values are Asset or Bundle.
lowestPrice	The lowest reseller price of the item (only returned if the item is resellable).
name	The item name.
price	The listing price of the item (current price may differ if the item is resellable).
priceStatus	The price status of an item that is not on sale. Possible values are Free, OffSale, or NoResellers.
purchaseCount	The purchase count of an item.
unitsAvailableForConsumption	The unit available for consumption of a limited unique item.

Library Catalog API

Library catalog items (non-avatar items) can be queried through the following API by including “CatalogContext=2” in the search query. Searching for Avatar Shop items should be done with the Avatar Catalog API.

https://search.roblox.com/catalog/json?CatalogContext=2&[params]

Query Parameters

Search parameters can be specified by appending a series of parameters and values to the URL, each separated by a &. For example:

https://search.roblox.com/catalog/json?CatalogContext=2&Category=4&PxMax=1000

Parameter	Type	Options and Values
CatalogContext	byte	Either omit this parameter or only use the DevelopOnly (=2) option to search for library catalog items. The AvatarOnly (=1) option has been deprecated and will result in an error. Use the Avatar Catalog API for avatar catalog item searches.
Category	byte	Models (=6), Plugins (=7), Decals (=8), Audio (=9), and Meshes (=10).
CreatorID	long	Specifies the `Player/UserId\|UserID` to filter in the search, for example 1 for Roblox. If you'd like to find group-created items, enter the group agent's ID, not the group ID.
CurrencyType	byte	All (=0), CustomRobux (=3), and Free (=5). Default is All. Use CustomRobux with custom PxMax and PxMin values. Specify Free for free items.
Genres	byte	Specifies the genre for the search. The options are TownAndCity (=1), Medieval (=2), SciFi (=3), Fighting (=4), Horror (=5), Naval (=6), Adventure (=7), Sports (=8), Comedy (=9), Western (=10), Military (=11), Building (=13), FPS (=14), and RPG (=15). The recommended approach to filtering on genres is to match the URL of a catalog page.
Keyword	string	Standard keyword search.
PageNumber	int	Specifies a page number in conjunction with ResultsPerPage to page through results.
PxMax	int	The maximum amount of Robux that an item can be priced in the query.
PxMin	int	The minimum amount of Robux that an item can be priced in the query.
ResultsPerPage	int	By default this is the same as what's currently shown on each catalog browse page. You can't specify a value larger than this maximum amount.
SortAggregation	byte	PastDay (=0), PastWeek (=1), PastMonth (=2), and AllTime (=3).
SortType	byte	Relevance (=0), MostFavorited (=1), Bestselling (=2), RecentlyUpdated (=3), PriceLowToHigh (=4), and PriceHighToLow (=5). Default is Relevance.

Example Search

This URL will search for 10 items in the “Models” subcategory, sorted by most recently updated.

https://search.roblox.com/catalog/json?CatalogContext=2&Category=6&SortType=3&ResultsPerPage=10

Response Format

Here’s an example of an item returned in articles/JSON Storage Format|JSON format:

{
	"AssetId": 3374795585,
	"Name": "Rat",
	"Description": "",
	"AbsoluteUrl": "https://www.roblox.com/catalog/3374795585/Rat",
	"Price": "",
	"Updated": "8 months ago",
	"Favorited": "80 times",
	"Sales": "1,613",
	"Remaining": "",
	"Creator": "ROBLOX",
	"CreatorAbsoluteUrl": "https://www.roblox.com/users/1/profile",
	"PrivateSales": "",
	"PriceView": 0,
	"BestPrice": "",
	"ContentRatingTypeID": 0,
	"IsServerSideThumbnailLookupInCatalogEnabled": true,
	"AudioUrl": null,
	"IsLargeItem": false,
	"IsThumbnailFinal": true,
	"IsThumbnailUnapproved": false,
	"ThumbnailUrl": "https://t1.rbxcdn.com/745a4be8c2366db2e55d0a67678434dc",
	"BcOverlayUrl": null,
	"LimitedOverlayUrl": null,
	"DeadlineOverlayUrl": null,
	"LimitedAltText": null,
	"NewOverlayUrl": null,
	"SaleOverlayUrl": null,
	"IosOverlayUrl": null,
	"XboxOverlayUrl": null,
	"GooglePlayOverlayUrl": null,
	"AmazonOverlayUrl": null,
	"IsTransparentBackground": false,
	"IsNewRobuxIconEnabled": true,
	"AssetTypeID": 10,
	"CreatorID": 1,
	"CreatedDate": "/Date(1561635090927)/",
	"UpdatedDate": "/Date(1562003916210)/",
	"IsForSale": false,
	"IsPublicDomain": true,
	"IsLimited": false,
	"IsLimitedUnique": false,
	"MinimumMembershipLevel": 0,
	"OffSaleDeadline": null,
	"ProductId": 586905093
}

Among the returned fields, note the following:

Field	Notes
AssetTypeID	One of the following asset type values: `3` = Audio `4` = Mesh `5` = Lua `10` = Model `13` = Decal `21` = Badge `24` = Animation `34` = GamePass `38` = Plugin `40` = MeshPart
BestPrice	This will be empty except for limited edition items, in which case it will return the best price for the item.
ContentRatingTypeID	`0` = No content rating type `1` = 13+ rated item
CreatedDate	Date the item was created in UTC format.
MinimumMembershipLevel	`0` = Any membership `4` = Roblox Premium only
Name	Item name in UTF-8 format.
PriceView	This is mostly used by the website to display prices. The options are: `0` = Free `1` = Collectible `2` = HasPrice `3` = NotForSale
PrivateSales	This will be empty except for limited edition items, in which case it will return the number of private sellers.
UpdatedDate	Date the item was last updated in UTC format.

Tags:

avatar
catalog
items