# TheRealReal API scraper — the largest US luxury consignment marketplace (therealreal.com): search and browse authenticated second-hand designer listings across women, men, jewelry, watches, art, home and kids with the site's own filters; read a full listing with its condition grade, measurements, materials and original retail price; refresh 50 listings in one call; and look up what comparable items ACTUALLY SOLD FOR. No account, no browser.

> Keyword search across the live catalogue with every filter the site exposes (category, designer, condition grade, colour, size, gender, store, price range, on-sale, vintage, with-tags, editors' picks) and its own sorts. Each row carries the asking price, the original retail estimate where the source publishes one, the condition grade, sold flag and images. Some brand/model terms ('birkin', 'kelly bag') are answered by the site with a curated collection instead of results — this action follows that redirect and says so in `followed_redirect`.
> ReefAPI engine `therealreal` · 11 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/therealreal/v1/<action>` with a JSON body.
- **Auth:** header `x-api-key: <YOUR_REEFAPI_KEY>` — create one free (1,000 credits, no card): https://reefapi.com/signup
- **Response (every call):** `{ ok: boolean, data: ..., meta: { record_count, credits, ... }, error: { code, message } }` — branch on `ok`. Failed calls are free except verified SHEIN NOT_FOUND on product/detail and price (4 credits).
- **One key + one shared credit pool** across every ReefAPI API. Per-call credits are listed on each endpoint below.
- **Use it from an AI agent (MCP):** connect `https://api.reefapi.com/mcp` (remote streamable-http). Send the key as `Authorization: Bearer <key>`, or put it in the URL (`?key=<key>`) when the client has no header field, as ChatGPT does.

## Endpoints

### POST https://api.reefapi.com/therealreal/v1/search — 1 credit
Keyword search across the live catalogue with every filter the site exposes (category, designer, condition grade, colour, size, gender, store, price range, on-sale, vintage, with-tags, editors' picks) and its own sorts. Each row carries the asking price, the original retail estimate where the source publishes one, the condition grade, sold flag and images. Some brand/model terms ('birkin', 'kelly bag') are answered by the site with a curated collection instead of results — this action follows that redirect and says so in `followed_redirect`.

**Parameters:**
- `query` (string, required) — Free-text search, e.g. 'chanel classic flap'.
- `currency` (enum, optional, default "USD") — Display currency for the *_display fields. Prices are ALSO always returned in USD, because the source converts the label only. [one of: USD, EUR, GBP, CAD, AUD, JPY, HKD, SGD, MXN]
- `page` (integer, optional, default 1) — 1-based page. The catalogue connection stops at 2000 rows.
- `page_size` (integer, optional, default 48) — Rows per page, 1-120 (the source's own ceiling).
- `sort` (enum, optional, default "newest") — Result order. [one of: newest, price_asc, price_desc, sold, most_obsessed]
- `follow_redirect` (boolean, optional, default true) — Follow the site's curated-collection redirect when a query returns one (default true). Set false to receive the redirect target untouched.
- `category` (string, optional) — Category permalink, e.g. 'women/handbags', 'men/shoes', 'jewelry/earrings', 'watches/bracelet'. Call `categories` for the live tree.
- `category_id` (array, optional) — Category facet id(s) from `filters`/`categories`.
- `designer` (string, optional) — Designer slug, e.g. 'chanel', 'saint-laurent', 'louis-vuitton'. Call `designers` for the full index.
- `designer_id` (array, optional) — Designer facet id(s) (from `designers`).
- `condition` (array, optional) — Condition grade(s) the site assigns. A numeric facet id is also accepted. [one of: pristine, excellent, very_good, good, fair, as_is]
- `color` (array, optional) — Colour / pattern facet(s). [one of: black, brown, burgundy, red, blue, purple, pink, orange, green, metallic, grey, yellow, white, gold, silver, animal_print, pattern_prints, neutrals, clear]
- `gender` (enum, optional) — Gender facet. [one of: women, men]
- `clothing_size` (array, optional) — Clothing size(s) (XS…5XL, Petite). [one of: petite, xxs, xs, s, m, l, xl, xxl, 3xl, 4xl, 5xl]
- `shoe_size` (array, optional) — US shoe size(s), 3.5-18. [one of: 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.5, 13, 13.5, 14, 14.5, 15, 15.5, 16, 16.5, 17, 18]
- `store_id` (array, optional) — Physical-store id(s) — items available in that TheRealReal store. `filters` lists them.
- `price_min` (number, optional) — Minimum asking price in USD.
- `price_max` (number, optional) — Maximum asking price in USD.
- `availability` (enum, optional, default "available") — 'available' hides sold listings (default); 'all' keeps them. Sold items are a real state on a one-of-a-kind marketplace, not an error. [one of: available, all]
- `on_sale` (boolean, optional, default false) — Only items the site currently marks as marked down.
- `vintage` (boolean, optional, default false) — Only items flagged vintage.
- `with_tags` (boolean, optional, default false) — Only items still carrying their original tags.
- `editors_picks` (boolean, optional, default false) — Only editors' picks.

**Returns:** results[{product_id, slug, sku, variant_id, name, url, designer, designer_id, artist, price, price_display, original_price, markdown_percent, discount_label, original_retail_price, original_retail_price_display, promotion, promotion_price, condition, color[], material[], size, gender, attributes{}, availability, sold, for_sale, on_hold, quantity, obsession_count, editors_pick, badge, images[]}], count, total_results_estimate, page, page_size, has_more, sort, currency, filters_applied, query, followed_redirect, redirect_to_sale

**Example request body:**
```json
{
  "query": "chanel classic flap",
  "page_size": 24
}
```

### POST https://api.reefapi.com/therealreal/v1/browse — 1 credit
Browse a category, a designer, a curated sale or any filter combination without a keyword — the catalogue view. Same row shape and sorts as `search`. At least one of category, category_id, designer, designer_id, sale_slug or a facet filter is required, so nobody accidentally pages through four million rows.

**Parameters:**
- `currency` (enum, optional, default "USD") — Display currency for the *_display fields. Prices are ALSO always returned in USD, because the source converts the label only. [one of: USD, EUR, GBP, CAD, AUD, JPY, HKD, SGD, MXN]
- `page` (integer, optional, default 1) — 1-based page. The catalogue connection stops at 2000 rows.
- `page_size` (integer, optional, default 48) — Rows per page, 1-120 (the source's own ceiling).
- `sort` (enum, optional, default "newest") — Result order. [one of: newest, price_asc, price_desc, sold, most_obsessed]
- `sale_slug` (string, optional) — A curated sale/collection slug, e.g. 'hermes-birkin-bag'. `search` reports one in `redirect_to_sale` when the site answers a query with a curated page.
- `category` (string, optional) — Category permalink, e.g. 'women/handbags', 'men/shoes', 'jewelry/earrings', 'watches/bracelet'. Call `categories` for the live tree.
- `category_id` (array, optional) — Category facet id(s) from `filters`/`categories`.
- `designer` (string, optional) — Designer slug, e.g. 'chanel', 'saint-laurent', 'louis-vuitton'. Call `designers` for the full index.
- `designer_id` (array, optional) — Designer facet id(s) (from `designers`).
- `condition` (array, optional) — Condition grade(s) the site assigns. A numeric facet id is also accepted. [one of: pristine, excellent, very_good, good, fair, as_is]
- `color` (array, optional) — Colour / pattern facet(s). [one of: black, brown, burgundy, red, blue, purple, pink, orange, green, metallic, grey, yellow, white, gold, silver, animal_print, pattern_prints, neutrals, clear]
- `gender` (enum, optional) — Gender facet. [one of: women, men]
- `clothing_size` (array, optional) — Clothing size(s) (XS…5XL, Petite). [one of: petite, xxs, xs, s, m, l, xl, xxl, 3xl, 4xl, 5xl]
- `shoe_size` (array, optional) — US shoe size(s), 3.5-18. [one of: 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.5, 13, 13.5, 14, 14.5, 15, 15.5, 16, 16.5, 17, 18]
- `store_id` (array, optional) — Physical-store id(s) — items available in that TheRealReal store. `filters` lists them.
- `price_min` (number, optional) — Minimum asking price in USD.
- `price_max` (number, optional) — Maximum asking price in USD.
- `availability` (enum, optional, default "available") — 'available' hides sold listings (default); 'all' keeps them. Sold items are a real state on a one-of-a-kind marketplace, not an error. [one of: available, all]
- `on_sale` (boolean, optional, default false) — Only items the site currently marks as marked down.
- `vintage` (boolean, optional, default false) — Only items flagged vintage.
- `with_tags` (boolean, optional, default false) — Only items still carrying their original tags.
- `editors_picks` (boolean, optional, default false) — Only editors' picks.

**Returns:** results[{product_id, slug, sku, variant_id, name, url, designer, designer_id, artist, price, price_display, original_price, markdown_percent, discount_label, original_retail_price, original_retail_price_display, promotion, promotion_price, condition, color[], material[], size, gender, attributes{}, availability, sold, for_sale, on_hold, quantity, obsession_count, editors_pick, badge, images[]}], count, total_results_estimate, page, page_size, has_more, sort, currency, filters_applied, sale_slug

**Example request body:**
```json
{
  "category": "women/handbags",
  "page_size": 24
}
```

### POST https://api.reefapi.com/therealreal/v1/product/detail — 1 credit
One listing in full, by slug or URL: name, designer, category path, the CONDITION GRADE plus the condition narrative the site writes, the seller description as clean lines, measurements with the unit as published, materials and colours, asking price with the markdown against the site's own previous price, the ORIGINAL RETAIL ESTIMATE where the source publishes one, sold state, return policy, disclaimers and every image with its dimensions. A sold listing resolves normally — it is a state, not an error.

**Parameters:**
- `slug` (string, optional) — Listing slug, e.g. 'saint-laurent-embossed-leather-clutch-wod8x' — the last path segment of a therealreal.com product URL. Every search/browse row returns it.
- `url` (string, optional) — A therealreal.com product URL instead of `slug`.

**Returns:** product{product_id, slug, sku, variant_id, name, url, designer, designer_id, artist, department, category, category_permalink, breadcrumb[{name, permalink, category_id}], condition, condition_description, description, description_lines[], measurements[{name, value}], measurement_unit, color[], material[], size, gender, attributes{}, price, price_display, original_price, markdown_percent, discount_label, original_retail_price, original_retail_price_display, promotion, availability, sold, for_sale, on_hold, quantity, obsession_count, editors_pick, badge, badge_tooltip, return_policy{returnable, description}, disclaimers[], sustainability{}, buy_now_eligible, valuation_report_url, images[{url, width, height}], image}

**Example request body:**
```json
{
  "slug": "hermes-2011-clemence-birkin-30-wlkvl"
}
```

### POST https://api.reefapi.com/therealreal/v1/products/batch — 2 credits
Up to 50 listings in ONE upstream call, by slug — the shape a catalogue refresh or a price/availability watcher should use instead of 50 separate detail calls. Slugs that no longer resolve come back in `not_found` rather than failing the call.

**Parameters:**
- `slugs` (array, required) — Up to 50 listing slugs (or product URLs), comma-separated or a JSON array.

**Returns:** products[{…same shape as product/detail…}], count, requested, not_found[]

**Example request body:**
```json
{
  "slugs": [
    "hermes-2011-clemence-birkin-30-wlkvl",
    "hermes-alligator-birkin-30-vh8n9",
    "hermes-togo-leather-birkin-30-v14oc"
  ]
}
```

### POST https://api.reefapi.com/therealreal/v1/product/similar — 1 credit
Visually similar LIVE listings for one product id — the answer to 'this one-of-a-kind item is sold, what else is like it'. Same row shape as search.

**Parameters:**
- `product_id` (string, required) — Numeric product id (every row and detail returns `product_id`).
- `only_similar` (boolean, optional, default true) — Restrict to close matches rather than the wider visual set.

**Returns:** results[{…row…}], count, product_id

**Example request body:**
```json
{
  "product_id": "52872453"
}
```

### POST https://api.reefapi.com/therealreal/v1/sold/search — 2 credits
SOLD comparables: what items matching a description actually sold for on TheRealReal, with the transacted price, the consignor commission percentage the site quotes on that price and the resulting payout, plus the condition grade of each comp. This is the resale pricing surface — the live catalogue only shows asking prices.

**Parameters:**
- `query` (string, required) — What sold, e.g. 'chanel classic flap' or 'hermes birkin 30'.
- `page` (integer, optional, default 1) — 1-based page. The catalogue connection stops at 2000 rows.
- `page_size` (integer, optional, default 48) — Rows per page, 1-120 (the source's own ceiling).
- `category` (string, optional) — Category permalink, e.g. 'women/handbags', 'men/shoes', 'jewelry/earrings', 'watches/bracelet'. Call `categories` for the live tree.
- `category_id` (array, optional) — Category facet id(s) from `filters`/`categories`.
- `designer` (string, optional) — Designer slug, e.g. 'chanel', 'saint-laurent', 'louis-vuitton'. Call `designers` for the full index.
- `designer_id` (array, optional) — Designer facet id(s) (from `designers`).
- `condition` (array, optional) — Condition grade(s) the site assigns. A numeric facet id is also accepted. [one of: pristine, excellent, very_good, good, fair, as_is]
- `color` (array, optional) — Colour / pattern facet(s). [one of: black, brown, burgundy, red, blue, purple, pink, orange, green, metallic, grey, yellow, white, gold, silver, animal_print, pattern_prints, neutrals, clear]
- `gender` (enum, optional) — Gender facet. [one of: women, men]
- `clothing_size` (array, optional) — Clothing size(s) (XS…5XL, Petite). [one of: petite, xxs, xs, s, m, l, xl, xxl, 3xl, 4xl, 5xl]
- `shoe_size` (array, optional) — US shoe size(s), 3.5-18. [one of: 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.5, 13, 13.5, 14, 14.5, 15, 15.5, 16, 16.5, 17, 18]
- `store_id` (array, optional) — Physical-store id(s) — items available in that TheRealReal store. `filters` lists them.
- `price_min` (number, optional) — Minimum asking price in USD.
- `price_max` (number, optional) — Maximum asking price in USD.
- `on_sale` (boolean, optional, default false) — Only items the site currently marks as marked down.
- `vintage` (boolean, optional, default false) — Only items flagged vintage.
- `with_tags` (boolean, optional, default false) — Only items still carrying their original tags.
- `editors_picks` (boolean, optional, default false) — Only editors' picks.

**Returns:** results[{product_id, slug, name, url, designer, designer_id, sold_price, sold_price_currency, consignor_commission_percent, consignor_payout, accepted_for_consignment, condition, color[], material[], size, attributes{}, images[]}], count, total_results_estimate, page, page_size, has_more, most_common_condition, commission_range{from, to, currency}, query

**Example request body:**
```json
{
  "query": "chanel classic flap",
  "page_size": 12
}
```

### POST https://api.reefapi.com/therealreal/v1/suggest — 1 credit
The search box's own autocomplete for a partial term — the cheapest way to find the phrasing the catalogue actually indexes.

**Parameters:**
- `query` (string, required) — Partial term, e.g. 'chan'.
- `limit` (integer, optional, default 10) — Max suggestions to return.

**Returns:** suggestions[{text}], count, query

**Example request body:**
```json
{
  "query": "chan"
}
```

### POST https://api.reefapi.com/therealreal/v1/trending — 1 credit
TheRealReal's own demand signal, as three ranked lists of designer + item-class pairs: what is selling fastest, what is most wishlisted and what is searched most. This is the site's own read on its market, not a metric this API computes.

**Parameters:**
- `limit` (integer, optional, default 50) — Max entries per list.

**Returns:** fastest_selling[], most_wishlisted[], most_searched[], counts{fastest_selling, most_wishlisted, most_searched}, count

**Example request body:**
```json
{
  "limit": 25
}
```

### POST https://api.reefapi.com/therealreal/v1/designers — 1 credit
The designer index for one department — 5 417 names for women, 2 745 for men — each with the facet id `browse` takes. Use `search`/`browse` with `designer` (slug) or `designer_id`.

**Parameters:**
- `category` (enum, optional, default "women") — Which directory to list. [one of: women, men, fine-jewelry, watches, art, home, kids]
- `query` (string, optional) — Filter the index by a name fragment, e.g. 'saint'.

**Returns:** designers[{designer_id, name, slug, restriction}], count, category, categories[]

**Example request body:**
```json
{
  "category": "watches"
}
```

### POST https://api.reefapi.com/therealreal/v1/categories — 1 credit
The live category tree with a live item count per node — the `category` permalinks every other action takes. Optionally scoped to one department or designer.

**Parameters:**
- `category` (string, optional) — Category permalink, e.g. 'women/handbags', 'men/shoes', 'jewelry/earrings', 'watches/bracelet'. Call `categories` for the live tree.
- `designer` (string, optional) — Designer slug, e.g. 'chanel', 'saint-laurent', 'louis-vuitton'. Call `designers` for the full index.
- `designer_id` (array, optional) — Designer facet id(s) (from `designers`).

**Returns:** departments[{category_id, name, permalink, count, children[{…}]}], count, total_results_estimate

**Example request body:**
```json
{
  "category": "women/handbags"
}
```

### POST https://api.reefapi.com/therealreal/v1/filters — 1 credit
Every facet the catalogue exposes for a given scope, with live counts and the exact ids the filter params take: condition grades, colours, clothing and shoe sizes, gender, designers, physical stores, the price range and the boolean flags. Call this instead of hard-coding an id.

**Parameters:**
- `currency` (enum, optional, default "USD") — Display currency for the *_display fields. Prices are ALSO always returned in USD, because the source converts the label only. [one of: USD, EUR, GBP, CAD, AUD, JPY, HKD, SGD, MXN]
- `category` (string, optional) — Category permalink, e.g. 'women/handbags', 'men/shoes', 'jewelry/earrings', 'watches/bracelet'. Call `categories` for the live tree.
- `category_id` (array, optional) — Category facet id(s) from `filters`/`categories`.
- `designer` (string, optional) — Designer slug, e.g. 'chanel', 'saint-laurent', 'louis-vuitton'. Call `designers` for the full index.
- `designer_id` (array, optional) — Designer facet id(s) (from `designers`).
- `condition` (array, optional) — Condition grade(s) the site assigns. A numeric facet id is also accepted. [one of: pristine, excellent, very_good, good, fair, as_is]
- `color` (array, optional) — Colour / pattern facet(s). [one of: black, brown, burgundy, red, blue, purple, pink, orange, green, metallic, grey, yellow, white, gold, silver, animal_print, pattern_prints, neutrals, clear]
- `gender` (enum, optional) — Gender facet. [one of: women, men]
- `clothing_size` (array, optional) — Clothing size(s) (XS…5XL, Petite). [one of: petite, xxs, xs, s, m, l, xl, xxl, 3xl, 4xl, 5xl]
- `shoe_size` (array, optional) — US shoe size(s), 3.5-18. [one of: 3.5, 4, 4.5, 5, 5.5, 6, 6.5, 7, 7.5, 8, 8.5, 9, 9.5, 10, 10.5, 11, 11.5, 12, 12.5, 13, 13.5, 14, 14.5, 15, 15.5, 16, 16.5, 17, 18]
- `store_id` (array, optional) — Physical-store id(s) — items available in that TheRealReal store. `filters` lists them.
- `price_min` (number, optional) — Minimum asking price in USD.
- `price_max` (number, optional) — Maximum asking price in USD.
- `availability` (enum, optional, default "available") — 'available' hides sold listings (default); 'all' keeps them. Sold items are a real state on a one-of-a-kind marketplace, not an error. [one of: available, all]
- `on_sale` (boolean, optional, default false) — Only items the site currently marks as marked down.
- `vintage` (boolean, optional, default false) — Only items flagged vintage.
- `with_tags` (boolean, optional, default false) — Only items still carrying their original tags.
- `editors_picks` (boolean, optional, default false) — Only editors' picks.

**Returns:** facets[{name, key, type, values[{id, label, count, permalink}], range{min, max}}], count, total_results_estimate, filters_applied

**Example request body:**
```json
{
  "category": "women/handbags"
}
```

## At scale
- **Volume:** 5M+ requests a day, measured at 60 requests a second across the fleet with no
  central bottleneck. Per-key limits are raised for high-volume accounts; volume pricing on request.
- **Missing a source:** tell us a site we do not cover and it becomes an engine. A customer asked
  for bestprice.gr on 21 Sep 2026 and it was in the catalog on 22 Sep.
- **Support:** 2 minute median time from a question in the live chat to the first answer. Setup
  help included, no support tier to buy.
- **One key, one credit pool** across every API. No per-site plans, no separate subscriptions.

## More
- Try it live, no code: https://reefapi.com/playground?engine=therealreal
- Human docs page: https://reefapi.com/docs/therealreal
- Overview page: https://reefapi.com/therealreal-api
- Every ReefAPI API in one file (for your AI): https://reefapi.com/llms-full.txt