--- title: "The RealReal API: JSON data, 2 endpoints, 1 credit per call" description: "The RealReal API for luxury consignment search by designer, condition and price, with original prices and product details as JSON. 1 credit per successful call." url: https://perceptlayer.com/apis/therealreal --- [APIs](https://perceptlayer.com/apis) / [Marketplaces](https://perceptlayer.com/verticals/marketplaces) / The RealReal 1 credit per call 2 endpoints 18 datapoints # The RealReal API The RealReal API for luxury consignment search by designer, condition and price, with original prices and product details as JSON. 1 credit per successful call. [Get a free API key](https://perceptlayer.com/signup) Run it below The RealReal GET /v1/therealreal/search?query=gucci+bag&condition\[\]=very-good&price\_max=500 ``` { "success": true, "items": [ { "id": "55468756", "sku": "GUC2174252", "name": "GG Canvas Joy", "url": "https://www.therealreal.com/products/women/handbags/totes/gucci-gg-canvas-joy-x0vys", "brand": "Gucci", "designer_id": "544", "price": 400, "original_price": 500, "currency": "USD", "discount_percent": 20, "availability": "available", "available": true, "sold": false, "quantity": 1, "condition": "Very Good", "gender": "Women", "favorites": 3, "images": [ "https://product-images.therealreal.com/GUC2174252_1_enlarged.jpg", "https://product-images.therealreal.com/GUC2174252_2_enlarged.jpg", "https://product-images.therealreal.com/GUC2174252_3_enlarged.jpg" ] }, { "id": "55333848", "sku": "GUC2169717", "name": "Nylon Shoulder Bag", "url": "https://www.therealreal.com/products/women/handbags/shoulder-bags/gucci-nylon-shoulder-bag-wxzvc", "brand": "Gucci", "designer_id": "544", "price": 380, "original_price": 475, "currency": "USD", "discount_percent": 20, "availability": "available", "available": true, "sold": false, "quantity": 1, "condition": "Very Good", "gender": "Women", "favorites": 4, "images": [ "https://product-images.therealreal.com/GUC2169717_1_enlarged.jpg", "https://product-images.therealreal.com/GUC2169717_2_enlarged.jpg", "https://product-images.therealreal.com/GUC2169717_3_enlarged.jpg" ] }, { "id": "55333672", "sku": "GUC2169709", "name": "Nylon Crossbody Bag", "url": "https://www.therealreal.com/products/women/handbags/crossbody-bags/gucci-nylon-crossbody-bag-wxzqg", "brand": "Gucci", "designer_id": "544", "price": 360, "original_price": 450, "currency": "USD", "discount_percent": 20, "availability": "available", "available": true, "sold": false, "quantity": 1, "condition": "Very Good", "gender": "Women", "favorites": 4, "images": [ "https://product-images.therealreal.com/GUC2169709_1_enlarged.jpg", "https://product-images.therealreal.com/GUC2169709_2_enlarged.jpg", "https://product-images.therealreal.com/GUC2169709_3_enlarged.jpg" ] } ], "pagination": { "page": 1, "per_page": 120, "total": 7825, "reachable": 2000, "returned": 120, "filtered_out": 0, "has_next_page": true }, "facets": [ { "name": "Categories", "parameter": "taxon_id", "buckets": [ { "id": "329", "name": "Women", "count": 6457, "path": "women" }, { "id": "495", "name": "Accessories", "count": 1365, "path": "women/accessories" }, { "id": "1603", "name": "Bag Accessories", "count": 36, "path": "women/accessories/bag-accessories" } ] }, { "name": "Clothing Sizes", "parameter": "clothing_size", "buckets": [ { "id": "22", "name": "Petite", "count": 2 }, { "id": "23", "name": "XXS", "count": 26 }, { "id": "24", "name": "XS", "count": 223 } ] }, { "name": "Shoe Sizes", "parameter": "shoe_size", "buckets": [ { "id": "30", "name": "4", "count": 14 }, { "id": "31", "name": "4.5", "count": 9 }, { "id": "32", "name": "5", "count": 51 } ] } ], "filters_applied": { "query": "gucci bag", "price_max": "500", "condition": [ "very-good" ] }, "meta": { "endpoint_family": "search", "request_id": "req_f1d4cacfe7514a8fa434c2097fd27d25", "credits_charged": 1, "credits_remaining": 1901 } } ``` 200 OK JSON X-Credits-Used: 1 Recorded from our API and shortened. Sample data ## What one call returns A recorded run of `search`: the fields and shapes you will get, shortened to 3 items. | # | id string | sku string | name string | url url | brand string | designer\_id string | price integer | original\_price integer | currency string | discount\_percent integer | availability string | available boolean | sold boolean | quantity integer | condition string | gender string | favorites integer | images string\[\] | | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | | 1 | 55468756 | GUC2174252 | GG Canvas Joy | https://www.therealreal.com/products/women/handbags/totes/gucci-gg-canvas-joy-x0vys | Gucci | 544 | 400 | 500 | USD | 20 | available | true | false | 1 | Very Good | Women | 3 | \[3 items\] | | 2 | 55333848 | GUC2169717 | Nylon Shoulder Bag | https://www.therealreal.com/products/women/handbags/shoulder-bags/gucci-nylon-shoulder-bag-wxzvc | Gucci | 544 | 380 | 475 | USD | 20 | available | true | false | 1 | Very Good | Women | 4 | \[3 items\] | | 3 | 55333672 | GUC2169709 | Nylon Crossbody Bag | https://www.therealreal.com/products/women/handbags/crossbody-bags/gucci-nylon-crossbody-bag-wxzqg | Gucci | 544 | 360 | 450 | USD | 20 | available | true | false | 1 | Very Good | Women | 4 | \[3 items\] | Recorded from our API · 3 items shown · 18 datapoints per item GET /v1/therealreal/search?query=gucci+bag&condition\[\]=very-good&price\_max=500 18 datapoints ### Identity - id string - sku string - name string - brand string - designer\_id string ### Contact - url url ### Reputation - images string\[\] ### Price - price integer - original\_price integer - currency string - discount\_percent integer ### Other - availability string - available boolean - sold boolean - quantity integer - condition string - gender string - favorites integer Playground ## Run this API cURL shell ``` curl "https://api.perceptlayer.com/v1/therealreal/search?query=gucci+bag&condition[]=very-good&price_max=500" \ -H "X-API-Key: $API_KEY" ``` The RealReal · 2 endpoints ## Endpoints Every endpoint takes the same key. Open one for its parameters and an example request. | Endpoint | Required parameters | Cost | | --- | --- | --- | | [GET `/v1/therealreal/product`](https://perceptlayer.com/apis/therealreal/product) | none +2 optional | 1 credit | | [GET `/v1/therealreal/search`](https://perceptlayer.com/apis/therealreal/search) | none +15 optional | 1 credit | Overview ## About the The RealReal API ## What you can get The RealReal API returns The RealReal consignment data as JSON through 2 endpoints. - **Search:** `search` takes a `query`, with `category`, `price_min`, `price_max`, `on_sale`, `with_tags`, `vintage`, `editors_picks` and `page`. `designer[]`, `color[]`, `clothing_size[]`, `shoe_size[]` and `taxon_id[]` are repeatable and take numeric ids; `condition[]` is repeatable and takes pristine, excellent, very-good, good, fair or as-is. - **Products:** `product` takes a `url` or a `sku`. The recorded search for "gucci bag" with `condition[]=very-good` and `price_max=500` returns `items`, each with `id`, `sku`, `name`, `url`, `brand`, `designer_id`, `price`, `original_price`, `currency`, `discount_percent`, `availability`, `sold`, `condition`, `gender`, `favorites` and `images`. It also returns `pagination` with `total` (7,825 in that recording), `reachable` and `has_next_page`, and `facets` whose buckets give the ids for `taxon_id[]`, `clothing_size[]` and `shoe_size[]`. ## How a call works Search, then look up: `GET /v1/therealreal/search?query=gucci bag&condition[]=very-good&price_max=500` with your key in the `X-API-Key` header. Each result carries a `url` and a `sku`, which `product` takes, and a `designer_id`, which `designer[]` takes. Every successful call costs 1 credit; failed calls cost nothing. Marketplaces JSON REST MCP ### More marketplaces APIs [About You](https://perceptlayer.com/apis/about-you) [adidas](https://perceptlayer.com/apis/adidas) [AliExpress](https://perceptlayer.com/apis/aliexpress) [Allegro](https://perceptlayer.com/apis/allegro) [Amazon](https://perceptlayer.com/apis/amazon) [ASOS](https://perceptlayer.com/apis/asos) [Billiger.de](https://perceptlayer.com/apis/billiger) [bol.com](https://perceptlayer.com/apis/bol) [Chrono24](https://perceptlayer.com/apis/chrono24) [Costco](https://perceptlayer.com/apis/costco) [Craigslist](https://perceptlayer.com/apis/craigslist) [DBA](https://perceptlayer.com/apis/dba) Use cases ### Track consignment prices for a designer by condition `Use the The RealReal API to track consignment prices for a designer by condition` ### Compare resale \`price\` with \`original\_price\` and \`discount\_percent\` `` Use the The RealReal API to compare resale `price` with `original_price` and `discount_percent` `` ### Find items with tags or vintage pieces with \`with\_tags\` and \`vintage\` `` Use the The RealReal API to find items with tags or vintage pieces with `with_tags` and `vintage` `` ### Watch on-sale items for a designer with \`on\_sale\` `` Use the The RealReal API to watch on-sale items for a designer with `on_sale` `` FAQ ## Questions **How much does The RealReal API cost?** Each successful call costs one credit, and each search page is one call. New accounts get free credits to start, and credit packs bring the price down as you scale. **Can I filter by condition?** Yes. \`condition\[\]\` is repeatable and takes pristine, excellent, very-good, good, fair or as-is. **Do I need an account with The RealReal?** No. You call this The RealReal API with your Perceptlayer key in the \`X-API-Key\` header, without a login at The RealReal. **What format are responses in?** Every endpoint returns JSON, with no HTML parsing on your side. **Should I build a The RealReal scraper instead?** You can, but a The RealReal scraper is code you maintain: page changes break it, requests get blocked, and The RealReal's terms govern how you collect data. The The RealReal API gives you 2 endpoints of named JSON fields for 1 credit per successful call, and failed calls cost nothing. A scraper makes sense only for data these endpoints don't return, so check the response in the playground on this page first. ## Try the The RealReal API with 100 free credits No credit card. Failed calls are never billed. [Get a free API key](https://perceptlayer.com/signup) [Read the docs](https://docs.perceptlayer.com)