therealreal.com APItherealreal.com ↗
Search and retrieve luxury resale listings from TheRealReal. Get prices, availability, condition, brand, and images via 2 structured endpoints.
curl -X GET 'https://api.parse.bot/scraper/fe22aec0-d60e-4015-b6ee-d769f4f18b1d/search_products?page=1&query=shoes' \ -H 'X-API-Key: $PARSE_API_KEY'
Search for products by keyword with pagination. Returns a list of products with basic info including price, availability status, and primary image. Each page contains up to 120 items.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number to retrieve |
| queryrequired | string | Search keyword (e.g. 'bags', 'shoes', 'Louis Vuitton') |
{
"type": "object",
"fields": {
"products": "array of product objects with keys: product_id, sku, name, brand, price, original_price, discount, status, url, primary_image",
"pagination": "object with keys: current_page (integer), total_items (integer or null)"
},
"sample": {
"data": {
"products": [
{
"sku": "JIM493525",
"url": "https://www.therealreal.com/products/women/shoes/sandals/jimmy-choo-leather-studded-accents-slides-u9g4q",
"name": "Leather Studded Accents Slides",
"brand": "Jimmy Choo",
"price": 132,
"status": "available",
"discount": "Now 20% off - $132.00",
"product_id": 50829290,
"primary_image": "https://product-images.therealreal.com/JIM493525_1_enlarged.jpg",
"original_price": 165
}
],
"pagination": {
"total_items": 2005,
"current_page": 1
}
},
"status": "success"
}
}About the therealreal.com API
The TheRealReal API provides access to luxury resale product data across 2 endpoints, covering search and detailed product retrieval. The search_products endpoint returns up to 120 items per page including price, discount, brand, availability status, and primary image. The get_product_details endpoint expands a single listing to include full description, condition, all product images, and canonical URL.
Search Luxury Resale Products
The search_products endpoint accepts a required query string — such as 'Louis Vuitton', 'bags', or 'shoes' — and an optional page integer for pagination. Each response returns an array of product objects with fields: product_id, sku, name, brand, price, original_price, discount, status, url, and primary_image. The pagination object reports current_page and total_items (which may be null for some queries). Pages hold up to 120 items each.
Product Detail Retrieval
The get_product_details endpoint accepts a full product url as returned by search_products. The response includes the complete field set for a single listing: sku, name, brand, price (in USD), currency, images (an array of all image URLs), condition (as a schema.org condition URL), description, and status. The status field resolves to one of three values: 'available', 'on_hold', or 'unknown', reflecting the current availability of the item.
Pricing and Condition Data
Both endpoints expose pricing information. search_products returns price, original_price, and a discount value, making it straightforward to identify marked-down items. get_product_details returns the current price alongside machine-readable condition data using schema.org URIs — useful for downstream classification without needing to parse freeform text. The description field provides the full listing text as shown on the product page.
- Track price drops on specific designer brands by comparing
priceagainstoriginal_pricefromsearch_products - Build a luxury resale price aggregator using
brand,name, anddiscountfields across paginated search results - Monitor availability shifts for specific items using the
statusfield (available,on_hold,unknown) - Populate a resale watchlist app with product images pulled from the
imagesarray inget_product_details - Classify secondhand items by condition using the schema.org
conditionURL returned in product details - Index TheRealReal listings by brand and category for a luxury goods search or comparison tool
- Analyze discount depth across a designer's catalog using
original_priceandpricefrom search results
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 250 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does TheRealReal have an official public developer API?+
What does the `status` field in `get_product_details` actually mean?+
'available' (purchasable), 'on_hold' (temporarily unavailable), or 'unknown' (status could not be determined). This is the same field returned by search_products, so you can pre-filter before fetching full details.Does `search_products` always return a `total_items` count?+
pagination object includes current_page and total_items, but total_items can be null depending on the query. You should handle a null value in any pagination logic rather than assuming the count is always present.Does the API return seller information or authentication certificates for listings?+
Can I filter `search_products` results by category, size, or price range directly in the request?+
query string and a page number. Category, size, and price-range filters are not currently supported as dedicated parameters — filtering on those dimensions would need to happen on the response data client-side. You can fork this API on Parse and revise it to add parameter-based filtering if your use case requires it.