Authenticated luxury consignment pricing research
Use The RealReal endpoints to turn authenticated luxury consignment pricing research into repeatable API requests with documented inputs and JSON responses.
Turn The RealReal's public authenticated luxury consignment catalog into structured JSON — keyword search with category, designer, condition-grade, and price-range filters, direct category and designer browsing, full listing detail with measurements and condition notes, the complete department/category taxonomy, the 5,000-plus-designer directory, and the 6-tier authentication condition scale. Normalized JSON, credential-free.
Search The RealReal's authenticated luxury consignment catalog, browse by category or designer, and get listing and condition-grade detail as structured JSON.
Endpoint families
6
Documented params
34
Examples
11
Live catalog snapshot
Active endpoints
11
Methods
GET
Required params
18
Schema refs
11
{
"platform": "The RealReal",
"endpoint": "therealreal-search",
"method": "GET",
"path": "/therealreal/search",
"auth": "apiKey"
}Use cases
Search The RealReal's authenticated luxury consignment catalog, browse by category or designer, and get listing and condition-grade detail as structured JSON.
Use The RealReal endpoints to turn authenticated luxury consignment pricing research into repeatable API requests with documented inputs and JSON responses.
Use The RealReal endpoints to turn condition-grade and designer demand tracking into repeatable API requests with documented inputs and JSON responses.
Use The RealReal endpoints to turn category and designer coverage monitoring into repeatable API requests with documented inputs and JSON responses.
Managed execution
Every figure below is read from the live The RealReal endpoint catalog — 11 endpoints, 34 documented request parameters, and 11 published response schemas — the same catalog Docs and Playground run against.
11 documented The RealReal endpoints, grouped into 11 request families — Autocomplete, Categories and Category, plus 8 more.
34 request parameters are documented across those The RealReal endpoints, 18 of them required — the full input contract is public before you write any integration code.
11 of the 11 The RealReal endpoints ship a recorded example response, and 11 carry a documented response schema — you can code against the real JSON before the first request.
The RealReal endpoints document their error responses (400, 404, 500 and 503) alongside the success schema, so a block, a rate limit, or a missing record comes back as a typed error rather than silently empty data.
11 hosted MCP tools back the The RealReal endpoints, so an agent can call the same routes with the same parameters and the same JSON contract, with no custom glue.
Coverage map
These cards are generated from the active endpoint catalog, so the landing page reflects the same API surface used by Docs and Playground.
/therealreal/autocomplete
/therealreal/categories
/therealreal/category
/therealreal/collection
/therealreal/collections
/therealreal/conditions
Endpoint catalog
/therealreal/searchSearches The RealReal's authenticated luxury resale catalog by keyword, optionally combined with category, designer, condition-grade, and price-range filters, returning normalized listing summaries (name, designer, condition, price, images) plus the total matching count and an opaque pagination cursor. Pass a previous response's next_after back as after to fetch the next page. Credential-free public data sourced from The RealReal's own server-rendered search page.
Response notes
- `total` reflects The RealReal's full matching-result count for the applied filters, not just `len(listings)`. - `next_after` is an opaque, server-issued pagination cursor. Pass it back as `after` (with the same `query`/filters) to fetch the next page. `has_more` is `false` once there is nothing further to page through. - A search with no matching listings returns `200` with `"listings": []`. - A missing `query` returns `400` before any upstream request is made. - `price_from` greater than `price_to` returns `400`. Example response: ```json { "code": 200, "msg": "OK", "data": { "total": 3643, "has_more": true, "next_after": "YXJyYXljb25uZWN0aW9uOjExOQ==", "listings": [ { "id": "54388578", "name": "Denim Pearl Crush Wallet On Chain", "sku": "CHA1494621", "designer": "Chanel", "designer_slug": "chanel", "condition": "Very Good", "color": "Blue", "gender": "Women", "price_usd": 3800, "original_price_usd": 3800, "available": true, "image_url": "https://product-images.therealreal.com/CHA1494621_1_enlarged.jpg", "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu" } ], "source_url": "https://www.therealreal.com/products?keywords=bag" } } ```
MCP tool therealreal_search
/therealreal/categoryReturns a page of normalized The RealReal listings browsed by category (taxon) permalink path, e.g. women/handbags. Pass a previous response's next_after back as after to fetch the next page. Credential-free public data sourced from The RealReal's own server-rendered category page.
Response notes
- Response shape matches [search](therealreal-search.md): `total`, `has_more`, `next_after`, `listings`. - An unrecognized `path` returns `404`. Example response: ```json { "code": 200, "msg": "OK", "data": { "total": 225361, "has_more": true, "next_after": "YXJyYXljb25uZWN0aW9uOjExOQ==", "listings": [ { "id": "54388578", "name": "Denim Pearl Crush Wallet On Chain", "designer": "Chanel", "condition": "Very Good", "price_usd": 3800, "available": true, "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu" } ], "source_url": "https://www.therealreal.com/shop/women/handbags" } } ```
MCP tool therealreal_category
/therealreal/designerReturns a page of normalized The RealReal listings browsed by designer slug, e.g. gucci. Pass a previous response's next_after back as after to fetch the next page. Credential-free public data sourced from The RealReal's own server-rendered designer page.
Response notes
- Response shape matches [search](therealreal-search.md): `total`, `has_more`, `next_after`, `listings`. - An unrecognized `slug` returns `404`. Example response: ```json { "code": 200, "msg": "OK", "data": { "total": 146120, "has_more": true, "next_after": "YXJyYXljb25uZWN0aW9uOjExOQ==", "listings": [ { "id": "54388579", "name": "GG Marmont Small Shoulder Bag", "designer": "Gucci", "condition": "Excellent", "price_usd": 950, "original_price_usd": 1980, "available": true, "url": "https://www.therealreal.com/products/women/handbags/shoulder-bags/gucci-gg-marmont-small-shoulder-bag-abcde" } ], "source_url": "https://www.therealreal.com/designers/gucci" } } ```
MCP tool therealreal_designer
/therealreal/listingReturns a single normalized The RealReal listing: description, condition detail, category context, and measurements, plus the shared summary fields (name, designer, condition, price, images). Looked up by the listing's full product URL, as returned in a search/category/designer response's url field. Credential-free public data sourced from The RealReal's own server-rendered listing page.
Response notes
- A `url` that isn't a `therealreal.com` `/products/...` listing URL returns `400`. - An unrecognized listing URL returns `404`. Example response: ```json { "code": 200, "msg": "OK", "data": { "id": "54388578", "name": "Denim Pearl Crush Wallet On Chain", "sku": "CHA1494621", "designer": "Chanel", "designer_slug": "chanel", "condition": "Very Good", "color": "Blue", "gender": "Women", "price_usd": 3800, "original_price_usd": 3800, "available": true, "images": [ "https://product-images.therealreal.com/CHA1494621_1_enlarged.jpg", "https://product-images.therealreal.com/CHA1494621_2_enlarged.jpg" ], "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu", "description": "Chanel Crossbody Bag, Blue Denim, Tweed Pattern...", "condition_detail": "Minor discoloration throughout; minor discoloration at hardware; minor scuff at corner.", "category_name": "Women", "category_label": "Women's Fashion & Accessories", "measurements": { "Height": "5\"", "Width": "7.5\"", "Shoulder Strap Drop": "19\"" }, "source_url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu" } } ```
MCP tool therealreal_listing
/therealreal/designersReturns every designer The RealReal recognizes in one department (not just designers with currently active listings), each with an id (usable directly against search's designer_id) and slug (usable directly against the designer endpoint). The directory is segmented by department -- pass category to select one; the response's categories field lists every accepted value. This is reference data that changes rarely, so responses are cached. Credential-free public data sourced from The RealReal's own server-rendered designer directory page.
Response notes
- This is reference data that changes rarely, so responses are cached for 24 hours per `category` value — repeated calls within that window return the cached result rather than re-fetching from The RealReal. - An unrecognized `category` returns `400`. Example response: ```json { "code": 200, "msg": "OK", "data": { "category": "women", "categories": [ {"name": "Women", "slug": "women"}, {"name": "Men", "slug": "men"}, {"name": "Fine Jewelry", "slug": "fine-jewelry"}, {"name": "Watches", "slug": "watches"}, {"name": "Art", "slug": "art"}, {"name": "Home", "slug": "home"}, {"name": "Kids", "slug": "kids"} ], "total": 5413, "designers": [ {"id": "267", "name": "Chanel", "slug": "chanel"}, {"id": "127", "name": "Gucci", "slug": "gucci"} ], "source_url": "https://www.therealreal.com/designers?category=women" } } ```
MCP tool therealreal_designers
/therealreal/categoriesReturns The RealReal's full category (taxon) browse taxonomy: every department, category, and subcategory, nested, with each entry's id (usable directly against search's category_id), permalink (usable directly against the category endpoint's path), and live matching item count. This is reference data that changes rarely, so responses are cached. Credential-free public data sourced from The RealReal's own server-rendered category page.
Response notes
- This is reference data that changes rarely, so responses are cached for 24 hours — repeated calls within that window return the cached result rather than re-fetching from The RealReal. - The taxonomy covers every top-level department The RealReal sells across (`women`, `men`, `jewelry`, `watches`, `art`, `home`, `kids`, `beauty`), nested arbitrarily deep — not just the department a particular fetch happens to be scoped to. Example response: ```json { "code": 200, "msg": "OK", "data": { "categories": [ { "id": "329", "name": "Women", "permalink": "women", "count": 2546988, "children": [ { "id": "493", "name": "Handbags", "permalink": "women/handbags", "count": 225361, "children": [ {"id": "548", "name": "Backpacks", "permalink": "women/handbags/backpacks", "count": 6926} ] } ] } ], "source_url": "https://www.therealreal.com/shop/women/handbags" } } ```
MCP tool therealreal_categories
/therealreal/conditionsReturns The RealReal's full authentication condition-grading scale: the closed 6-tier set (Pristine, Excellent, Very Good, Good, Fair, As Is) it defines, each with an id (usable directly against search's condition_id) and live matching item count. This is reference data that changes rarely, so responses are cached. Credential-free public data sourced from The RealReal's own server-rendered category page.
Response notes
- This is reference data that changes rarely, so responses are cached for 24 hours — repeated calls within that window return the cached result rather than re-fetching from The RealReal. - The condition grades are, from best to worst: `Pristine`, `Excellent`, `Very Good`, `Good`, `Fair`, `As Is`. Example response: ```json { "code": 200, "msg": "OK", "data": { "conditions": [ {"id": "18", "name": "Pristine", "count": 11840}, {"id": "19", "name": "Excellent", "count": 73390}, {"id": "20", "name": "Very Good", "count": 162975}, {"id": "30560", "name": "Good", "count": 123448}, {"id": "655545", "name": "Fair", "count": 27403}, {"id": "2988045", "name": "As Is", "count": 5105} ], "source_url": "https://www.therealreal.com/shop/women/handbags" } } ```
MCP tool therealreal_conditions
/therealreal/autocompleteReturns The RealReal's own search-box typeahead suggestions for a partial query. Credential-free public data sourced from The RealReal's own first-party catalog API.
Response notes
- A missing `term` returns `400` before any upstream request is made. - A `term` with no suggestions returns `200` with `"suggestions": []`. Example response: ```json { "code": 200, "msg": "OK", "data": { "suggestions": [ {"text": "gucci"}, {"text": "gucci handbags"}, {"text": "gucci shoes"} ], "source_url": "https://api.therealreal.com/graphql" } } ```
MCP tool therealreal_autocomplete
/therealreal/collectionReturns a page of normalized The RealReal listings browsed by curated collection slug, e.g. on-sale-now -- sale campaigns, editor's picks, and similar merchandising collections distinct from category/designer browsing. Pass a previous response's next_after back as after to fetch the next page. Credential-free public data sourced from The RealReal's own server-rendered collection page.
Response notes
- Response shape matches [search](therealreal-search.md): `total`, `has_more`, `next_after`, `listings`. - An unrecognized `slug` returns `404`. Example response: ```json { "code": 200, "msg": "OK", "data": { "total": 2218390, "has_more": true, "next_after": "YXJyYXljb25uZWN0aW9uOjExOQ==", "listings": [ { "id": "54388578", "name": "Denim Pearl Crush Wallet On Chain", "designer": "Chanel", "condition": "Very Good", "price_usd": 3800, "available": true, "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu" } ], "source_url": "https://www.therealreal.com/sales/on-sale-now" } } ```
MCP tool therealreal_collection
/therealreal/collectionsReturns The RealReal's full published set of curated editorial and sale-campaign collection slugs (e.g. on-sale-now, hermes-birkin-bag), each usable directly against the collection endpoint's own slug field. This is reference data that changes rarely, so responses are cached. Credential-free public data sourced from The RealReal's own published sitemap.
Response notes
- This is reference data that changes rarely, so responses are cached for 24 hours — repeated calls within that window return the cached result rather than re-fetching from The RealReal. - The full set is discovered from The RealReal's own sitemap rather than scraped from on-site navigation links, which only surface a small fraction of the published collections. Example response: ```json { "code": 200, "msg": "OK", "data": { "total": 535, "collections": [ {"slug": "on-sale-now", "url": "https://www.therealreal.com/sales/on-sale-now"}, {"slug": "hermes-birkin-bag", "url": "https://www.therealreal.com/sales/hermes-birkin-bag"} ], "source_url": "https://www.therealreal.com/sitemaps/sales1.xml" } } ```
MCP tool therealreal_collections
/therealreal/similarReturns The RealReal's own "Similar Items" visual-similarity recommendations for one product, looked up by the product's numeric id (from any other The RealReal endpoint's listing response id field). Credential-free public data sourced from The RealReal's own first-party catalog API.
Response notes
- Unlike search/category/designer, this is not paginated — The RealReal's own visual-similarity carousel returns a single fixed-size list, not a cursor-paged connection. - `product_id` must be numeric; a non-numeric value returns `400` before any upstream request is made. Example response: ```json { "code": 200, "msg": "OK", "data": { "listings": [ { "id": "47942591", "name": "Shadow Denim Wallet On Chain", "sku": "CHA1343119", "designer": "Chanel", "designer_slug": "chanel", "price_usd": 3127.5, "original_price_usd": 3475, "available": true, "image_url": "https://product-images.therealreal.com/CHA1343119_1_enlarged.jpg", "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-shadow-denim-wallet-on-chain-sjkqn" } ], "source_url": "https://api.therealreal.com/graphql" } } ```
MCP tool therealreal_similar
Related APIs
Marketplaces & Retail
Collect marketplace product signals from Amazon without building brittle storefront scrapers.
Marketplaces & Retail
Build resale, pricing, and marketplace workflows from structured eBay data.
Marketplaces & Retail
Turn public Shop.app product and merchant pages into structured JSON for e-commerce product intelligence, price research, shop monitoring, and marketplace discovery workflows.
How to scrape The RealReal
Crawlora's seven The RealReal endpoints return search, category/designer browse, listing, designer, category, and condition data as normalized JSON with one API key — categories, designers, and conditions are 24-hour-cached reference data, since they change far less often than listings.
Call /therealreal/categories for the full nested department/category/subcategory tree, /therealreal/designers (with an optional category department, defaulting to women, since each department carries a materially different list) for the designer directory, and /therealreal/conditions for the fixed 6-tier scale (Pristine through As Is) — all three cached 24 hours and feeding directly into search's own filters.
Send query (required — The RealReal only applies filters and pagination alongside a keyword; without one the underlying page serves an unrelated promotional collection instead) plus optional category_id, designer_id, condition_id, price_from, and price_to to /therealreal/search. next_after is an opaque cursor — pass it back as after with the same query and filters for the next page, until has_more is false.
Pass a category permalink (e.g. women/handbags) to /therealreal/category, or a designer slug (e.g. gucci) to /therealreal/designer, both from their respective discovery endpoints — same has_more/next_after/listings response shape as search, but without needing a keyword.
Pass a listing's full product url (from any search/category/designer result's own url field) to /therealreal/listing for its description, condition_detail notes, measurements, and category context — The RealReal's listing URLs are opaque slugs with no separate numeric-id lookup, so the full URL is the only reliable key.
FAQ
Because The RealReal's own underlying search page only applies category/designer/condition/price filters and honors pagination when a keyword query is also present — without one, the page serves an unrelated promotional collection instead of a filtered result set. Use /therealreal/category or /therealreal/designer instead for keyword-free browsing.
Pass a designer slug from /therealreal/designers (e.g. gucci) to /therealreal/designer for a paginated listing feed for that designer, in the same has_more/next_after/listings shape as search — no keyword needed.
/therealreal/conditions returns the fixed 6-tier scale from best to worst: Pristine, Excellent, Very Good, Good, Fair, and As Is, each with an id usable as search's condition_id and a live matching-item count.
Over 5,000 in the women department alone (5,413 as of the last verified count) — /therealreal/designers takes a category department (women, men, fine-jewelry, watches, art, home, or kids, defaulting to women) since each carries a materially different designer list.
No — only your Crawlora API key. Search, category, designer, listing, and condition data are collected from The RealReal's public, credential-free, server-rendered pages.