# The RealReal Search API Documentation

The RealReal Search API Documentation Search The RealReal luxury consignment in the US. Every item has the id, SKU, url, name, brand and designer id, price, original price and retail price (msrp) as numbers with currency, discount percent, availability (available, on_hold or sold), condition, gender, badge, favorites and full size photos. Each response also carries the filter facets (categories, designers, conditions, colors, sizes, price range) with their ids and counts, so you can build the next filter without a second request. Every filter is checked against the filters the site applied: a filter the site did not apply returns an error, never unfiltered items. A page holds up to 120 items; the site serves the first 2000 items of a listing. Sorting is not available. Sold prices, seller and listing date are not public. A search costs 1 credit per request. An empty page, a failed request and a 404 are not billed.

- **Documentation:** [https://scrappa.co/docs/therealreal-api/therealreal_search](https://scrappa.co/docs/therealreal-api/therealreal_search) - **API group:** The RealReal API - **Endpoint:** `GET https://scrappa.co/api/therealreal/search` ## Authentication Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `query` | string | No | Search text, e.g. gucci bag or a SKU. Required unless you send a category. | | `category` | string | No | Category path from the Categories facet, e.g. women/handbags. Cannot be combined with query or taxon_id. | | `taxon_id` | string | No | Category id from the Categories facet, comma separated. Use it to narrow a query search to a category. | | `designer` | string | No | Designer ids from the Designers facet, comma separated, e.g. 544 for Gucci. | | `condition` | string | No | pristine, excellent, very-good, good, fair or as-is, comma separated. | | `color` | string | No | Color ids from the Color facet, comma separated. | | `clothing_size` | string | No | Clothing size ids from the Clothing Sizes facet, comma separated. | | `shoe_size` | string | No | Shoe size ids from the Shoe Sizes facet, comma separated. | | `price_min` | number | No | Lowest price in USD. | | `price_max` | number | No | Highest price in USD. | | `on_sale` | boolean | No | true to return only items with a price drop. | | `with_tags` | boolean | No | true to return only items with tags. | | `vintage` | boolean | No | true to return only vintage items. | | `editors_picks` | boolean | No | true to return only editors picks. | | `page` | integer | No | Page number, default 1. Each page has 120 items. The site serves the first 2000 items, so the page is at most 17. | ## Example response ```json { "meta": { "credits": 6, "billable": true, "endpoint_family": "search" }, "items": [ { "id": "55945611", "sku": "GUC2188017", "url": "https://www.therealreal.com/products/women/handbags/handle-bags/gucci-gg-signature-sukey-medium-xb3wr", "msrp": null, "name": "GG Signature Sukey Medium", "sold": false, "badge": null, "brand": "Gucci", "price": 365, "gender": "Women", "images": [ "https://product-images.therealreal.com/GUC2188017_1_enlarged.jpg", "https://product-images.therealreal.com/GUC2188017_2_enlarged.jpg" ], "currency": "USD", "quantity": 1, "available": true, "condition": "Good", "favorites": 0, "designer_id": "544", "availability": "available", "original_price": 365, "discount_percent": null, "discount_percent_vs_msrp": null }, { "id": "1", "sku": "TEST000001", "url": "https://www.therealreal.com/products/women/handbags/handle-bags/gucci-gg-canvas-punch-xb40c", "msrp": 1000, "name": "GG Canvas Punch", "sold": true, "badge": null, "brand": "Gucci", "price": 420, "gender": "Women", "images": [ "https://product-images.therealreal.com/GUC2188022_1_enlarged.jpg", "https://product-images.therealreal.com/GUC2188022_2_enlarged.jpg" ], "currency": "USD", "quantity": 1, "available": false, "condition": "Good", "favorites": 0, "designer_id": "544", "availability": "sold", "original_price": 420, "discount_percent": null, "discount_percent_vs_msrp": 58 } ], "facets": [ { "name": "Categories", "buckets": [ { "id": "329", "name": "Women", "path": "women", "count": 32900 }, { "id": "495", "name": "Accessories", "path": "women/accessories", "count": 3061 } ], "parameter": "taxon_id" }, { "name": "Clothing Sizes", "buckets": [ { "id": "22", "name": "Petite", "count": 7 }, { "id": "23", "name": "XXS", "count": 47 } ], "parameter": "clothing_size" }, { "name": "Shoe Sizes", "buckets": [ { "id": "1983459", "name": "3.5", "count": 2 }, { "id": "30", "name": "4", "count": 35 } ], "parameter": "shoe_size" } ], "success": true, "pagination": { "page": 1, "total": 10355, "per_page": 120, "returned": 2, "reachable": 2000, "filtered_out": 0, "has_next_page": true }, "filters_applied": { "query": "gucci bag", "condition": [ "very-good" ], "price_max": 500 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. | | 422 | Unknown Category | The RealReal has no listing for this category path. This response is not billable. | | 422 | Curated Search Term | The RealReal turns some search terms, such as a brand name, into a curated sale page that has no search result. This response is not billable. Use a more specific term or the designer filter. | | 503 | Source Unavailable | The RealReal did not give a usable answer after the retries. This response is not billable. Retry later. | ## More Scrappa resources - [API documentation](https://scrappa.co/docs) - [Full LLM-readable API reference](https://scrappa.co/llms-full.txt) - [OpenAPI specification](https://scrappa.co/docs/api.json) - [Pricing](https://scrappa.co/pricing)