Luxury resale with the two numbers that matter, the grade and the sold price
The TheRealReal API returns the largest US luxury consignment marketplace as clean JSON in eleven actions.
11 active endpoints, on 0, 1 and 2 credit tiers.
- POST/therealreal/v1/search
- POST/therealreal/v1/browse
- POST/therealreal/v1/product/detail
- POST/therealreal/v1/products/batch
- POST/therealreal/v1/product/similar
- POST/therealreal/v1/sold/search
- POST/therealreal/v1/suggest
- +4 more
What TheRealReal endpoints does ReefAPI ship?
11 live read endpoints. Read-only data API: no writes, no account actions, no dashboard access on the target site.
TheRealReal API
6 of 11 endpoints, ready to run
Keyword search across the live catalogue: asking price, condition grade, designer, colour, material, size, the original retail estimate where TheRealReal publishes one, and every image. Up to 120 rows a page.
// Press "Try it" and this pane shows exactly what the // live site returned this second — including an empty // result, if that is the truth. No key, no account.
How the TheRealReal API works
TheRealReal is a normal ReefAPI surface — the same four rules that hold for every other engine on the key.
No OAuth app, no request signing, no per-site account. One key covers all 294 engines.
Every route is a POST with a JSON body. Parameters are validated against the published schema before anything is charged.
Credits, not seats. Failed and blocked calls are never charged, and cache hits cost nothing.
One envelope everywhere. meta carries latency_ms, record_count and the endpoint that answered.
Settle the slugs first, because the index actions are free
TheRealReal answers a category permalink or a designer slug it does not recognise with its entire catalogue rather than with an error, which is the one way a request here can look successful and mean nothing. designers, categories and filters cost nothing, so there is no reason to guess.
{"category": "watches", "query": "rolex"}Zero credits. The designer index for one department with the exact slug and facet id the other actions take, 5,417 names for women and 2,745 for men. The directory and the catalogue disagree on one word, fine-jewelry against jewelry, and both are accepted here.
{"category": "women/handbags"}Zero credits. Every facet for that scope with a live count and the id each filter parameter takes: six condition grades, nineteen colours, eleven clothing sizes, twenty-nine shoe sizes, two genders, the physical stores and the live price range, which read $7 to $731,500 when measured.
{"category": "women/handbags", "designer": "chanel", "condition": ["excellent"], "price_min": 2000, "page_size": 120}1 credit for up to 120 rows. Store each row's slug and product_id. The catalogue stops at 2,000 rows per query, so narrowing by condition, colour, size or price band is how you reach the rest, and total_results_estimate tells you how big the pool is.
{"slugs": ["<50 stored slugs>"]}2 credits for up to 50 listings in one call, which is the whole point of it. Slugs that no longer resolve come back in not_found instead of failing the call, so a watchlist refresh tells you what has gone as well as what has been marked down or put on hold.
{"query": "chanel classic flap", "page_size": 12}2 credits. What comparable items actually sold for, with the commission percentage TheRealReal quotes on that price and the resulting payout. This is the only surface here that carries a transacted price.
A watchlist keyed on slugs you can refresh 50 at a time, and an asking price you can set against what the market actually paid.
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}'{
"ok": true,
"data": { … },
"meta": {
"api": "therealreal",
"endpoint": "search",
"mode": "live",
"latency_ms": …,
"record_count": …
},
"error": null
}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.
Seven departments, six grades, and the fields TheRealReal does not publish
Measured 2026-09-24 over 135 live calls through the engine, across thirteen categories, thirteen queries, thirteen designers and fourteen listings, shuffled so that no action got a clean run of its own. Every action came back at 100 percent. Three of these lines go against us.
women, men, jewelry, watches, art, home and kids. TheRealReal's own count of available listings read 3.81 million on the day of measurement, with 3.16 million marked down, 405,196 still carrying their original tags, 142,600 editors' picks and 139,484 flagged vintage. That count moves: the same filter minutes apart gave 442,369, then 387,928, then 392,486, then 330,248, which is why it is returned as total_results_estimate rather than as a total.
312 of 312 rows across thirteen categories carried one, and so did 312 of 312 image sets. Six grades, returned as TheRealReal writes them: Pristine, Excellent, Very Good, Good, Fair and As Is. A detail record adds the condition narrative written for that specific item, which is a different thing from the grade and is returned in its own field.
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. Where the source is silent the field is null. It is never estimated, and no percentage off retail is derived from it, because TheRealReal does not publish one.
sold/search returns the price a matching item actually sold for, the commission percentage TheRealReal quotes on that price, the resulting consignor payout, the condition grade of each comparable and the commission range for the set. 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, so read the rows rather than the query.
USD, EUR, GBP, CAD, AUD, JPY, HKD, SGD and MXN, probed one at a time. TheRealReal converts the label only, so price stays in US dollars in all nine and price_display carries the converted text. The same item came back as $545.00, €491.37 and ¥88,528 on one underlying amount, and both fields are returned so that nobody re-keys a converted number.
120 rows a request, which is the source's own ceiling, and no deeper than row 2,000 whatever the match count says. A deeper request is refused here rather than quietly re-served. Narrowing by designer, category, condition, colour, size, store or price band is how you reach the rest, and the index actions that hand you those ids are free.
TheRealReal publishes neither, 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. It publishes no seller identity, no serial number, no model, no year of production, no view count and no rating either. Consignors are anonymous by design, so there is no seller surface and no personal data is returned.
The material facet comes back on search and browse rows, where it was present on 24 of 24 shoe and handbag rows, 14 of 24 women's accessory rows and 10 of 24 men's accessory rows, and absent by category elsewhere. TheRealReal does not publish it on the detail record at all, checked on 8 of 8 listings, so there the material sits inside the seller's own description and is returned verbatim in description_lines. Carry the facet forward from the row that found the item. Size behaves the same way: 24 of 24 on clothing and shoes, 17 of 24 on kids, 5 of 24 on women's accessories, and nothing on jewellery, watches, handbags or art.
suggest, designers, categories and filters are free. search, browse, product/detail, product/similar and trending are 1 credit each. products/batch is 2 credits for up to 50 listings, and sold/search is 2. A 120-row page and a single listing both cost 1 credit, so ask for the page, and refresh a watchlist in batches of 50 rather than one call at a time.
What people build with TheRealReal
The jobs this data is most often used for.
endpoints
credits per call
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.
What TheRealReal data costs
The cheapest call here is 0 credits, so $15/mo (Pro) buys 10,000 of them — $1.50 per 1,000 credits. Credits roll over and never expire, and failed or blocked calls are not charged.
Full pricing →- 1,000 free credits on signup, no card
- One key, all 294 APIs, one credit pool
- Failed and blocked calls are never charged
- Credits roll over and never expire
Call it in two lines
Sign up, get 1,000 credits and one key that works on every engine. Then this is the whole protocol.
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"])Have a question? We got answers.
The questions people actually ask before wiring up TheRealReal.
Get a free key →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.
122 E-commerce & Marketplaces APIs on the same key
One key, one credit pool, one response envelope. If you are pulling TheRealReal, you are one call away from the rest of the category — no second contract, no second integration.
Need something this API does not do?
Name the endpoint, the field, or a source we do not carry yet. We ship new APIs every week and you would be first to get the key. Real people read every message and reply the same day.
Try it on your own data before you pay anything
The call above is the real endpoint, not a recording. A free key gives you 1,000 credits, the other 293 APIs, and the same envelope everywhere.
Endpoints, parameters and credit costs on this page are read from the live catalog and cannot drift from what the API accepts. Field notes were captured on 2026-09-24.