TheRealReal APItherealreal.com ↗
Search and retrieve luxury resale listings from TheRealReal. Get prices, availability, condition, brand, and images via 2 structured endpoints.
What is the TheRealReal 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.
curl -X GET 'https://api.parse.bot/scraper/fe22aec0-d60e-4015-b6ee-d769f4f18b1d/search_products?page=1&query=bags' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace therealreal-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
"""Walkthrough: TheRealReal SDK — search luxury products and drill into details."""
from parse_apis.TheRealReal_API import TheRealReal, Product, ProductDetail, ProductNotFound
client = TheRealReal()
# Search for luxury handbags, capped at 5 total items
for product in client.products.search(query="Chanel handbag", limit=5):
print(product.name, product.brand, product.price, product.status)
# Drill into the first result for full details (images, condition, description)
item = client.products.search(query="Louis Vuitton", limit=1).first()
if item:
detail = item.details()
print(detail.name, detail.condition, detail.availability, len(detail.images))
# Typed error handling: catch ProductNotFound on a bad URL
try:
bad_item = Product(_api=client, product_id="nonexistent", url="https://www.therealreal.com/products/women/handbags/does-not-exist-xyz")
bad_item.details()
except ProductNotFound as exc:
print(f"Product not found: {exc.url}")
print("exercised: products.search / product.details / ProductNotFound error")
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. Results are ordered by relevance by default.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number to retrieve (1-based) |
| 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": "WJQ68724",
"url": "https://www.therealreal.com/products/women/handbags/handle-bags/jacquemus-leather-le-petit-bambimou-small-u9upo",
"name": "Leather Le Petit Bambimou Small",
"brand": "Jacquemus",
"price": 483.75,
"status": "available",
"discount": "Now 25% off - $483.75",
"product_id": "50848188",
"primary_image": "https://product-images.therealreal.com/WJQ68724_1_enlarged.jpg",
"original_price": 645
}
],
"pagination": {
"total_items": 56366,
"current_page": 1
}
},
"status": "success"
}
}About the TheRealReal API
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.
The TheRealReal API is a managed, monitored endpoint for therealreal.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when therealreal.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official therealreal.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- 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 | 100 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.