The RealReal API endpoint
Searches The RealReal's authenticated luxury resale catalog by keyword, optionally combined with category, designer, condition-grade, and price-range filters, returning 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.
/therealreal/searchQuery parameters:
query (required) — free-text keyword search. The RealReal only applies
the filters below (and honors pagination) when a keyword search is also
present; without one, the underlying page serves an unrelated
promotional collection instead.category_id (optional) — category (taxon) id, from the
categories endpoint's id field.designer_id (optional) — designer id, from the
designers endpoint's id field.condition_id (optional) — condition grade id, from the
conditions endpoint's id field.price_from (optional) — minimum price in USD.price_to (optional) — maximum price in USD.on_sale (optional) — when true, only return items currently marked
down from their original price.available (optional) — when true, only return items currently
available to purchase (excludes sold and waitlisted items).after (optional) — an opaque pagination cursor from a previous
response's next_after. Omit for the first page.Notable response behavior:
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.200 with "listings": [].query returns 400 before any upstream request is made.price_from greater than price_to returns 400.| Field | Filled in, of 120 checked | Values in the sample |
|---|---|---|
| id | 120 | |
| name | 120 | “GG Canvas Shoulder Bag” and 98 other values |
| sku | 120 | |
| designer | 120 | Gucci in all 120 |
| condition | 120 | Good (38), Fair (26), As Is (19) and 3 more |
| gender | 120 | |
| price_usd | 120 | 126 to 6,400, median 436 |
| original_price_usd | 120 | 165 to 8,000, median 565 |
| available | 120 | true in 117 of 120 |
| image_url | 120 | product-images.therealreal.com |
| images | 120 | median 6 entries |
| url | 120 | therealreal.com |
| Parameter | Type | Required | Default | Description | Example |
|---|---|---|---|---|---|
| query | string | Yes | Free-text keyword search | gucci bag | |
| category_id | string | No | Category (taxon) id, from the categories endpoint's id field | 493 | |
| designer_id | string | No | Designer id, from the designers endpoint's id field | 127 | |
| condition_id | string | No | Condition grade id, from the conditions endpoint's id field | 20 | |
| price_from | number | No | Minimum price in USD | 100 | |
| price_to | number | No | Maximum price in USD | 1000 | |
| on_sale | boolean | No | Only return items currently marked down from their original price | ||
| available | boolean | No | Only return items currently available to purchase (excludes sold and waitlisted items) | ||
| after | string | No | Opaque pagination cursor from a previous response's next_after. Omit for the first page | ||
| x-api-key (header) | string | Yes | API key required |
curl -X GET "https://api.crawlora.net/api/v1/therealreal/search?query=gucci+bag&on_sale=true&available=true" \ -H "x-api-key: $CRAWLORA_API_KEY"
{
"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"
}
}Request schema
No body schema
Response schema
#/definitions/therealreal.searchResponseDoc
| Field | Type | Required | Enum | Bounds | Example | Description |
|---|---|---|---|---|---|---|
| code | integer | No | 200 | |||
| data | therealreal.ProductsResponse | No | ||||
| data.has_more | boolean | No | true | |||
| data.listings | array | No | ||||
| data.listings[].available | boolean | No | true | |||
| data.listings[].color | string | No | Blue | |||
| data.listings[].condition | string | No | Very Good | |||
| data.listings[].designer | string | No | Chanel | |||
| data.listings[].designer_slug | string | No | chanel | |||
| data.listings[].gender | string | No | Women | |||
| data.listings[].id | string | No | 54388578 | |||
| data.listings[].image_url | string | No | https://product-images.therealreal.com/CHA1494621_1_enlarged.jpg | |||
| data.listings[].images | array | No | ||||
| data.listings[].name | string | No | Denim Pearl Crush Wallet On Chain | |||
| data.listings[].original_price_usd | number | No | 3800 | |||
| data.listings[].price_usd | number | No | 3800 | |||
| data.listings[].sku | string | No | CHA1494621 | |||
| data.listings[].url | string | No | https://www.therealreal.com/products/women/handbags/crossbody-bags/chanel-denim-pearl-crush-wallet-on-chain-wdqhu | |||
| data.listings[].waitlisted | boolean | No | false | |||
| data.next_after | string | No | YXJyYXljb25uZWN0aW9uOjExOQ== | |||
| data.source_url | string | No | ||||
| data.total | integer | No | 404167 | |||
| msg | string | No | OK |
| Status | Description | Schema |
|---|---|---|
| 400 | Bad Request | #/definitions/app.Response |
| 500 | Internal Server Error | #/definitions/app.Response |
| 503 | Service Unavailable | #/definitions/app.Response |
Use environment variables for secrets and keep Crawlora API keys server-side.
curl -X GET "https://api.crawlora.net/api/v1/therealreal/search?query=gucci+bag&on_sale=true&available=true" \
-H "x-api-key: $CRAWLORA_API_KEY"