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.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
15 optional filters available.
string
Optional
Search text, e.g. gucci bag or a SKU. Required unless you send a category.
coffee shops
string
Optional
Category path from the Categories facet, e.g. women/handbags. Cannot be combined with query or taxon_id.
example
string
Optional
Category id from the Categories facet, comma separated. Use it to narrow a query search to a category.
1234567890
string
Optional
Designer ids from the Designers facet, comma separated, e.g. 544 for Gucci.
example
string
Optional
pristine, excellent, very-good, good, fair or as-is, comma separated.
example
string
Optional
Color ids from the Color facet, comma separated.
example
string
Optional
Clothing size ids from the Clothing Sizes facet, comma separated.
example
string
Optional
Shoe size ids from the Shoe Sizes facet, comma separated.
example
number
Optional
Lowest price in USD.
10
number
Optional
Highest price in USD.
10
boolean
Optional
true to return only items with a price drop.
true
boolean
Optional
true to return only vintage items.
true
boolean
Optional
true to return only editors picks.
true
integer
Optional
Page number, default 1. Each page has 120 items. The site serves the first 2000 items, so the page is at most 17.
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
meta
items
facets
success
pagination
filters_applied
Common items fields
id
sku
url
msrp
{
"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
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A query parameter is missing or invalid. This response is not billable.
{
"errors": {
"category": [
"Send a search text or a category."
]
},
"message": "The request validation failed"
}Unknown Category
The RealReal has no listing for this category path. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "search"
},
"error": {
"code": "INVALID_REQUEST",
"message": "The RealReal has no listing for this category. Use a category path from the facets of a search result, e.g. women/handbags."
},
"success": false
}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.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "search"
},
"error": {
"code": "INVALID_REQUEST",
"message": "The RealReal turns this search term into a curated sale page, so it has no search result. Use a more specific term, or filter by designer with the designer facet."
},
"success": false
}Source Unavailable
The RealReal did not give a usable answer after the retries. This response is not billable. Retry later.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "upstream_unavailable",
"message": "The RealReal is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.