TheRealReal API & Scraper
The TheRealReal API returns the largest US luxury consignment marketplace as clean JSON in eleven actions.
🤖 Using an AI assistant? Copy this link into ChatGPT / Claude / Cursor — it reads every endpoint and parameter instantly and tells you if this API fits your use case.
search takes a free-text query and browse takes a category permalink, a designer slug or a curated sale slug, and both return up to 120 rows a page in the same shape: product_id, slug, sku, name, url, designer, the asking price in US dollars, price_display in whichever of the nine currencies you asked for, original_price and markdown_percent against the site's own previous price, discount_label, original_retail_price where TheRealReal publishes one, the condition grade, color, material, size, gender, obsession_count, editors_pick and every image. product/detail adds the condition narrative TheRealReal writes for that specific item, the seller description as description_lines, measurements with measurement_unit, the category breadcrumb, return_policy, disclaimers and image dimensions. products/batch resolves up to 50 slugs in one call and puts the ones that no longer resolve in not_found instead of failing the call, which is the shape a catalogue refresh or a price watcher wants. product/similar answers the question a one-of-a-kind marketplace forces on you, which is what else is like the item that has just gone. sold/search is the surface the live catalogue does not have: it returns what matching items actually sold for as sold_price, with consignor_commission_percent, consignor_payout, most_common_condition and commission_range. trending returns TheRealReal's own three demand lists, fastest_selling, most_wishlisted and most_searched. suggest, designers, categories and filters are free index actions that hand you the exact slugs, permalinks and facet ids the filters take: 5,417 designer names for women and 2,745 for men, the live category tree with a count per node, and the facet enums, six condition grades, nineteen colours, eleven clothing sizes, twenty-nine US shoe sizes, two genders, the physical stores and the live price range. Seventeen filter parameters, five sort orders, and three availability states reported separately, for sale, on hold and sold. Measured 2026-09-24 over 135 live calls across thirteen categories, thirteen queries, thirteen designers and fourteen listings: every action at 100 percent, and a condition grade on 312 of 312 rows. No TheRealReal account, no browser, one ReefAPI key and the standard { ok, data, meta, error } envelope.
Six TheRealReal values that are not what they look like
TheRealReal is a one-of-a-kind marketplace, so several fields mean something narrower than they appear to, and one of them will hand you four million rows if you let it. These were read from live calls on 2026-09-24.
| Field | Looks like | Actually is | What comes back |
|---|---|---|---|
| condition | one field | two different things. On a search or browse row it is the grade. On a detail record TheRealReal writes a narrative instead, such as "No visible signs of wear." | condition holds the grade and condition_description holds the narrative, so the two never overwrite each other |
| price and price_display | the same number in the currency you asked for | TheRealReal converts the label only. The underlying amount stays in US dollars in all nine currencies | price is always USD and price_display carries the converted text. One item came back as $545.00, €491.37 and ¥88,528 on the same underlying amount |
| availability | in stock or gone | three states. 720 rows over six categories: 692 available, 28 on hold, plus sold. On hold is an item sitting in somebody's basket and still live | sold, for_sale and on_hold are separate, so an on-hold listing is never reported as gone |
| total_results_estimate | the number of matches | an estimate that moves. The same filter minutes apart gave 442,369, then 387,928, then 392,486, then 330,248 | returned as total_results_estimate, named so that nobody budgets against it as a count |
| markdown_percent | how far below retail the item is | the site's own previous asking price against the current one, both of which TheRealReal publishes. No percentage is ever worked out against the retail estimate | markdown_percent, plus discount_label in the site's own wording, which appeared on 15 of 24 art rows and almost nowhere else |
| an unrecognised category or designer slug | an empty result | TheRealReal answers it with its whole catalogue instead of an error. A nonsense permalink returned 3,791,675 rows and a nonsense designer 3,776,457 | the call is refused with NOT_FOUND and points at categories or designers, rather than passing back four million rows that mean nothing |
Measured 2026-09-24. A condition grade came back on 312 of 312 rows across thirteen categories. material is on search and browse rows, but TheRealReal does not publish it on the detail record, checked on 8 of 8 listings, so there the material sits inside the seller description and is returned verbatim in description_lines.
Real request and response JSON
Captured from the indexed primary action, search, on .
{
"method": "POST",
"url": "https://api.reefapi.com/therealreal/v1/search",
"headers": {
"x-api-key": "$REEF_KEY",
"content-type": "application/json"
},
"body": {
"query": "chanel classic flap",
"page_size": 24
}
}{
"ok": true,
"meta": {
"api": "therealreal",
"endpoint": "search",
"mode": "live",
"latency_ms": 2246.8,
"record_count": 24,
"bytes": 29207,
"cache_hit": false,
"pagination": {
"page": 1,
"page_size": 24,
"total": 3639,
"has_more": true
},
"charged_credits": 1,
"version": "0.1.0"
},
"data": {
"results": [
{
"product_id": "54584754",
"slug": "chanel-cc-flap-bag-whxv6",
"sku": "CHA1499101",
"variant_id": "111564046",
"name": "CC Flap Bag",
"url": "https://www.therealreal.com/products/women/handbags/shoulder-bags/chanel-cc-flap-bag-whxv6",
"designer": "Chanel",
"designer_id": "267",
"artist": null,
"price": 2500,
"price_display": "$2,500.00",
"original_price": null,
"markdown_percent": null,
"discount_label": null,
"original_retail_price": null,
"original_retail_price_display": null,
"promotion": null,
"promotion_price": null,
"condition": "As Is",
"color": [],
"material": [],
"size": null,
"gender": "Women",
"attributes": {
"condition": [
"[trimmed-depth]"
],
"gender": [
"[trimmed-depth]"
]
},
"availability": "AVAILABLE",
"sold": false,
"for_sale": true,
"on_hold": false,
"quantity": "1",
"obsession_count": "[redacted-secret]",
"editors_pick": false,
"badge": null,
"images": [
"https://product-images.therealreal.com/CHA1499101_1_enlarged.jpg",
"https://product-images.therealreal.com/CHA1499101_2_enlarged.jpg",
"https://product-images.therealreal.com/CHA1499101_3_enlarged.jpg"
]
},
{
"product_id": "54719712",
"slug": "chanel-classic-rectangular-mini-flap-bag-wku00",
"sku": "CHA1502282",
"variant_id": "111833964",
"name": "Classic Rectangular Mini Flap Bag",
"url": "https://www.therealreal.com/products/women/handbags/shoulder-bags/chanel-classic-rectangular-mini-flap-bag-wku00",
"designer": "Chanel",
"designer_id": "267",
"artist": null,
"price": 4800,
"price_display": "$4,800.00",
"original_price": null,
"markdown_percent": null,
"discount_label": null,
"original_retail_price": 5600,
"original_retail_price_display": "$5,600.00",
"promotion": null,
"promotion_price": null,
"condition": "Very Good",
"color": [],
"material": [],
"size": null,
"gender": "Women",
"attributes": {
"condition": [
"[trimmed-depth]"
],
"gender": [
"[trimmed-depth]"
]
},
"availability": "AVAILABLE",
"sold": false,
"for_sale": true,
"on_hold": false,
"quantity": "1",
"obsession_count": "[redacted-secret]",
"editors_pick": true,
"badge": "Editors' Pick",
"images": [
"https://product-images.therealreal.com/CHA1502282_1_enlarged.jpg",
"https://product-images.therealreal.com/CHA1502282_2_enlarged.jpg",
"https://product-images.therealreal.com/CHA1502282_3_enlarged.jpg"
]
},
{
"product_id": "54843697",
"slug": "chanel-vintage-2-55-double-flap-bag-wnho1",
"sku": "CHA1505300",
"variant_id": "112081883",
"name": "Vintage 2.55 Double Flap Bag",
"url": "https://www.therealreal.com/products/women/handbags/shoulder-bags/chanel-vintage-2-55-double-flap-bag-wnho1",
"designer": "Chanel",
"designer_id": "267",
"artist": null,
"price": 4895,
"price_display": "$4,895.00",
"original_price": null,
"markdown_percent": null,
"discount_label": null,
"original_retail_price": 11700,
"original_retail_price_display": "$11,700.00",
"promotion": null,
"promotion_price": null,
"condition": "As Is",
"color": [],
"material": [],
"size": null,
"gender": "Women",
"attributes": {
"condition": [
"[trimmed-depth]"
],
"gender": [
"[trimmed-depth]"
]
},
"availability": "AVAILABLE",
"sold": false,
"for_sale": true,
"on_hold": false,
"quantity": "1",
"obsession_count": "[redacted-secret]",
"editors_pick": false,
"badge": null,
"images": [
"https://product-images.therealreal.com/CHA1505300_1_enlarged.jpg",
"https://product-images.therealreal.com/CHA1505300_2_enlarged.jpg",
"https://product-images.therealreal.com/CHA1505300_3_enlarged.jpg"
]
}
],
"count": 24,
"total_results_estimate": 3639,
"page": 1,
"page_size": 24,
"has_more": true,
"max_reachable_rows": 2000,
"sort": "newest",
"currency": "USD",
"filters_applied": {
"availability": "available"
},
"query": "chanel classic flap",
"followed_redirect": false,
"redirect_to_sale": null,
"redirect_url": null
}
}What the TheRealReal API does
| Action | Description | Concrete use case | Key params |
|---|---|---|---|
| search | Keyword search across the live catalogue with every filter the site exposes (category, designer, condition grade, colour, size, gender, store, price range, on-sale, vintage, with-tags, editors' picks) and its own sorts. Each row carries the asking price, the original retail estimate where the source publishes one, the condition grade, sold flag and images. Some brand/model terms ('birkin', 'kelly bag') are answered by the site with a curated collection instead of results — this action follows that redirect and says so in `followed_redirect`. | Pricing teams call search to get keyword search across the live catalogue with every filter the site exposes (category, design…. | query, currency, page, page_size, sort, ... |
| browse | Browse a category, a designer, a curated sale or any filter combination without a keyword — the catalogue view. Same row shape and sorts as `search`. At least one of category, category_id, designer, designer_id, sale_slug or a facet filter is required, so nobody accidentally pages through four million rows. | Marketplace operators call browse to get browse a category, a designer, a curated sale or any filter combination without a keyword. | currency, page, page_size, sort, sale_slug, ... |
| product/detail | One listing in full, by slug or URL: name, designer, category path, the CONDITION GRADE plus the condition narrative the site writes, the seller description as clean lines, measurements with the unit as published, materials and colours, asking price with the markdown against the site's own previous price, the ORIGINAL RETAIL ESTIMATE where the source publishes one, sold state, return policy, disclaimers and every image with its dimensions. A sold listing resolves normally — it is a state, not an error. | Catalog enrichment teams call product/detail to get one listing in full, by slug or URL. | slug, url |
| products/batch | Up to 50 listings in ONE upstream call, by slug — the shape a catalogue refresh or a price/availability watcher should use instead of 50 separate detail calls. Slugs that no longer resolve come back in `not_found` rather than failing the call. | Retail analysts call products/batch to get up to 50 listings in ONE upstream call, by slug. | slugs |
| product/similar | Visually similar LIVE listings for one product id — the answer to 'this one-of-a-kind item is sold, what else is like it'. Same row shape as search. | Pricing teams call product/similar to get visually similar LIVE listings for one product id. | product_id, only_similar |
| sold/search | SOLD comparables: what items matching a description actually sold for on TheRealReal, with the transacted price, the consignor commission percentage the site quotes on that price and the resulting payout, plus the condition grade of each comp. This is the resale pricing surface — the live catalogue only shows asking prices. | Marketplace operators call sold/search to get sOLD comparables. | query, page, page_size, category, category_id, ... |
| suggest | The search box's own autocomplete for a partial term — the cheapest way to find the phrasing the catalogue actually indexes. | Catalog enrichment teams call suggest to get the search box's own autocomplete for a partial term. | query, limit |
| trending | TheRealReal's own demand signal, as three ranked lists of designer + item-class pairs: what is selling fastest, what is most wishlisted and what is searched most. This is the site's own read on its market, not a metric this API computes. | Retail analysts call trending to get theRealReal's own demand signal, as three ranked lists of designer + item-class pairs. | limit |
| designers | The designer index for one department — 5 417 names for women, 2 745 for men — each with the facet id `browse` takes. Use `search`/`browse` with `designer` (slug) or `designer_id`. | Pricing teams call designers to get the designer index for one department. | category, query |
| categories | The live category tree with a live item count per node — the `category` permalinks every other action takes. Optionally scoped to one department or designer. | Marketplace operators call categories to get the live category tree with a live item count per node. | category, designer, designer_id |
| filters | Every facet the catalogue exposes for a given scope, with live counts and the exact ids the filter params take: condition grades, colours, clothing and shoe sizes, gender, designers, physical stores, the price range and the boolean flags. Call this instead of hard-coding an id. | Catalog enrichment teams call filters to get every facet the catalogue exposes for a given scope, with live counts and the exact ids the f…. | currency, category, category_id, designer, designer_id, ... |
Call search from your stack
curl -X POST https://api.reefapi.com/therealreal/v1/search \
-H "x-api-key: $REEF_KEY" \
-H "content-type: application/json" \
-d '{"query":"chanel classic flap","page_size":24}'import requests
r = requests.post(
"https://api.reefapi.com/therealreal/v1/search",
headers={"x-api-key": REEF_KEY},
json={
"query": "chanel classic flap",
"page_size": 24
},
)
print(r.json()["data"])const res = await fetch("https://api.reefapi.com/therealreal/v1/search", {
method: "POST",
headers: {
"x-api-key": process.env.REEF_KEY,
"content-type": "application/json",
},
body: JSON.stringify({
"query": "chanel classic flap",
"page_size": 24
}),
});
const { ok, data, meta, error } = await res.json();Ask your MCP-connected assistant: call reefapi.therealreal.search with {"query":"chanel classic flap","page_size":24}.Who uses this API and why
- Price a bag, watch or piece of jewellery against what comparable items actually sold for rather than against asking prices.
- Track a designer's live stock, condition mix and markdowns across women, men, jewelry, watches, art, home and kids.
- Build a resale index of original retail estimate against current asking price, by designer and category.
- Refresh a watchlist of thousands of listings 50 at a time and see which have been marked down, put on hold or sold.
- Follow TheRealReal's own demand lists, fastest selling, most wishlisted and most searched, as a resale trend signal.
Questions developers ask before integrating
Does TheRealReal API return the condition grade?
Yes, on every row. 312 of 312 rows across thirteen categories carried one. TheRealReal's own six grades are returned as it writes them: Pristine, Excellent, Very Good, Good, Fair and As Is, and condition also takes those words as a filter. A detail record additionally returns the condition narrative written for that specific item, such as "Minor pilling throughout", in condition_description. The grade and the narrative are different things and are kept in different fields.
Does it return the original retail price?
Where TheRealReal publishes one, and how often that happens depends entirely on the category, so it is measured rather than promised. On the 24 newest rows per category: 23 of 24 bracelet watches, 22 of 24 jewellery bracelets, 21 of 24 earrings, 16 of 24 men's and women's shoes, 14 of 24 men's clothing, 10 of 24 women's clothing, 4 of 24 women's handbags, 2 of 24 home decor, and 0 of 24 on accessories, art and kids. When the source is silent, original_retail_price is null. It is never estimated, and no percentage off retail is derived from it.
Can I get what items actually sold for?
Yes, from sold/search, which is a different surface from the live catalogue. It returns items matching a description with sold_price, the commission percentage TheRealReal quotes on that price in consignor_commission_percent, the resulting consignor_payout, the condition grade of each comp, most_common_condition for the set and commission_range. The live catalogue carries asking prices only. One caveat worth knowing: the matching is TheRealReal's own and it weights the designer heavily and the model lightly, so a query for rolex submariner returned 10 comps that were all Rolex bags. They are real sold items at real transacted prices, they are simply not all the model asked for.
Is a sold listing an error?
No. Almost every item here is one of a kind, so sold is a normal state: the listing still resolves and keeps its price, grade, measurements and images. Three states are reported separately, for sale, on hold and sold, because on hold means the item is in somebody's basket and is still live. Search and browse hide sold listings by default and availability set to all keeps them.
Who is the seller on TheRealReal?
TheRealReal does not publish it. Items are consigned and the consignor is anonymous by design, so there is no seller name, rating, profile or history on any action, and no personal data is returned. The commission percentage and the payout that sold/search returns are the figures TheRealReal quotes publicly against a sold price, not anybody's account.
How deep can I page?
Up to 120 rows a request, which is TheRealReal's own ceiling, and no deeper than row 2,000 per query whatever the match count says. Beyond that the source stops serving rows, so a deeper request is refused here rather than answered with an empty page. Narrowing is how you reach the rest: designer, category, condition, colour, clothing or shoe size, store, price band, on sale, vintage, with tags and editors' picks are all filters, and the index actions that hand you the exact ids cost nothing.
Which filters and sort orders are there?
Seventeen filter parameters: category and category_id, designer and designer_id, condition, color, gender, clothing_size, shoe_size, store_id, price_min, price_max, availability, on_sale, vintage, with_tags and editors_picks. Five sort orders: newest, price_asc, price_desc, sold and most_obsessed. Call filters for the live facet ids and counts, categories for the permalinks and designers for the slugs. Getting a slug right matters here, because TheRealReal answers one it does not recognise with its entire catalogue rather than an error. Its slugs fold accents and drop ampersands rather than spelling them out, so Dolce & Gabbana is dolce-gabbana and Alice + Olivia is alice-olivia. Display names are slugified for you.
What does TheRealReal not publish?
No listing date and no sold date, so days on site and sold on cannot be built from this data. Sorting by newest still works, because the source orders by a date it does not show. No seller identity, no serial number, no model, no year of production, no view count, no rating and no reviews. The material facet is on search and browse rows but not on the detail record, so carry it forward from the row that found the item, or read the seller's own wording in description_lines. Everything absent comes back null rather than guessed.
What is the TheRealReal API?
TheRealReal API is a ReefAPI endpoint group for authenticated luxury resale: condition grades, original retail estimates and what comparable items actually sold for. It returns live JSON through POST requests under /therealreal/v1.
Is the TheRealReal API free to try?
Yes. ReefAPI starts with 1,000 free credits, no card required. TheRealReal calls use the same shared credit balance as every other ReefAPI engine.
Do I need a TheRealReal login or account?
No login to TheRealReal is needed for the API response. You call ReefAPI with your x-api-key header, and the playground can run live examples before you create a production key.
How fresh is the TheRealReal data?
The page example is captured from a live search call, and production requests fetch live data through ReefAPI rather than a static sample.
How many credits does the TheRealReal API use?
TheRealReal actions currently cost 1-2 credits per successful call. Failed or blocked calls are free. All APIs draw from one credit pool.
Can I call TheRealReal from an AI assistant or MCP client?
Yes. Connect ReefAPI once through MCP and your assistant can call therealreal actions with the same key, credit pool and JSON envelope used by normal REST requests.