# The RealReal Scraper (`crawlerbros/therealreal-scraper`) Actor Scrape The RealReal - the largest online marketplace for authenticated luxury resale. Browse by category or designer, or fetch full product detail (price, condition, size, measurements, authentication info, images) by product URL. - **URL**: https://apify.com/crawlerbros/therealreal-scraper.md - **Developed by:** [Crawler Bros](https://apify.com/crawlerbros) (community) - **Categories:** E-commerce, Automation, Agents - **Stats:** 2 total users, 1 monthly users, 100.0% runs succeeded, 0 bookmarks - **User rating**: No ratings yet ## Pricing from $3.00 / 1,000 results This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage. Since this Actor supports Apify Store discounts, the price gets lower the higher subscription plan you have. Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#pay-per-event ## What's an Apify Actor? Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows. In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours, and optionally produces a well-defined JSON output, datasets with results, or files in key-value store. In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server. Actors are written with capital "A". ## How to integrate an Actor? If asked about integration, you help developers integrate Actors into their projects. You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready. The best way to integrate Actors is as follows. In JavaScript/TypeScript projects, use official [JavaScript/TypeScript client](https://docs.apify.com/api/client/js/docs.md): ```bash npm install apify-client ``` In Python projects, use official [Python client library](https://docs.apify.com/api/client/python/docs.md): ```bash pip install apify-client ``` In shell scripts, use [Apify CLI](https://docs.apify.com/cli/docs.md): ````bash # MacOS / Linux curl -fsSL https://apify.com/install-cli.sh | bash # Windows irm https://apify.com/install-cli.ps1 | iex ```bash In AI frameworks, you might use the [Apify MCP server](https://docs.apify.com/integrations/mcp.md). If your project is in a different language, use the [REST API](https://docs.apify.com/api/v2.md). For usage examples, see the [API](#api) section below. For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt). # README ## The RealReal Scraper Scrape [The RealReal](https://www.therealreal.com) — the world's largest online marketplace for authenticated luxury resale. Browse by department/category or by designer, or fetch complete product detail (price, condition, size, measurements, authentication info, images) for any product URL. ### What this actor does - **Five modes:** `byCategory`, `byDesigner`, `byUrl`, `discoverCategories`, `discoverDesigners` - **Full taxonomy coverage:** browse by department (women / men / jewelry / watches / art / home / kids / beauty) and a curated set of 50+ common subcategories, plus a free-text override for any category path on the site - **`discoverCategories` mode** — lists the site's own real, complete, cross-department category tree (department → category → subcategory), each with a live product count, straight from the same "Refine Results" facet data the site's own sidebar reads. One cheap fetch, zero anti-bot risk. Use it to find real `categoryPath`/`customCategoryPath` values beyond the curated dropdown. - **`discoverDesigners` mode** — lists up to 200 real designer/brand names for a department (optionally scoped to a category), each with a live product count and internal numeric ID, from the same facet data. One cheap fetch — reliable when scoped to just a department (the default), same best-effort anti-bot caveat as `byCategory`/`byDesigner` applies if you also set a specific `categoryPath`/`customCategoryPath`, since that fetches that exact taxon page rather than the always-reliable anchor `discoverCategories` uses. Solves the previous "guess a free-text `designerSlug`" problem — every returned `designerSlug` is verified to resolve to real `byDesigner` results. - **Designer/brand browse:** any of The RealReal's thousands of designer slugs (e.g. `chanel`, `hermes`, `louis-vuitton`), optionally filtered to a department - **Full item detail:** price (incl. estimated retail and any discount), condition grade, size, color, material, measurements, category breadcrumb, authentication note, return policy text, disclaimer text, sustainability (carbon/water saved), images - **Marketing browse axes:** `sale` and `new-arrivals` are available as curated `categoryPath` options (in addition to the 50+ taxonomy categories), confirmed to return real, currently-live listings - **Department-aware size/material:** the GraphQL `size`-carrying attribute type differs by department (clothing `CLOTHING_SIZE`/`FOREIGN_SIZE`, shoes `SHOE_SIZE`, jewelry `RING_SIZE`, art `ART_SIZE`, watches `CASE_DIAMETER`, kids `KIDS_*`/`INFANTS_*`/`TODDLERS_*`) and material is `METAL_TYPE` for jewelry instead of `PRIMARY_MATERIAL`/`FABRIC` — `size`/`material` are resolved across every known type so they populate on every department, not just clothing (verified live 2026-07-26 across all 7 departments) - **Filters:** price range, condition, color, size, material, movement type (watches), case material (watches), on-sale-only - **Jewelry detail:** carat weight (ctw, summed across stones), clarity grade, color grade, gemstone, stone type, stone shape(s) — verified live 2026-07-26 against the site's own jewelry-department attribute data - **Watch detail:** model name, reference number, collection, movement type, case material, band material, watch style(s), complications — verified live 2026-07-26 against the site's own watches-department attribute data - **Dress/menswear detail:** dress silhouette (e.g. "Wrap Dress") and men's chest size band — verified live 2026-07-27 against the site's own dresses/men's-clothing attribute data - **Empty fields are omitted** — every record only contains fields the source actually disclosed ### Output per product | Field | Notes | |---|---| | `productId`, `sku` | | | `variantId` | The specific listing's internal variant ID | | `name`, `brand`, `brandId` | `brandId` is the brand's internal numeric designer ID | | `department`, `categoryPath`, `categoryBreadcrumb[]` | breadcrumb only on `byUrl` | | `condition` | As Is / Fair / Good / Very Good / Excellent / Pristine | | `conditionNotes` | `byUrl` only — the item's real free-text condition description (e.g. "No visible signs of wear", "Minor scratches throughout metal; Minor wear at strap"), distinct from the `condition` grade above | | `size`, `color`, `gender`, `material` | `size`/`material` resolved across department-specific attribute types (clothing/shoe/ring/art/watch/kids sizes; fabric or metal-type material) so they populate on every department, not just clothing | | `artistId` | Art department only — the piece's internal artist ID (artist name is already in `brand`) | | `caratWeight`, `clarityGrade`, `colorGrade`, `gemstone`, `stoneType`, `stoneShapes[]` | Jewelry department only — `caratWeight` is the total carat weight summed across all stones of that type on the item | | `watchModel`, `referenceNumber`, `watchCollection`, `movementType`, `caseMaterial`, `bandMaterial`, `watchStyles[]`, `complications[]` | Watches department only | | `dressSilhouette` | Dresses category only — e.g. "Wrap Dress", "Slip Dress", "Evening Gown" (verified live 2026-07-27: 100% populated on real dresses listings) | | `chestSize` | Men's clothing only — chest size band (e.g. "42", "48 +"), when the designer reports it alongside `size` | | `priceUsd`, `priceFormatted` | current price | | `originalPriceUsd`, `originalPriceFormatted` | only present if discounted from a prior TRR price | | `estRetailPriceUsd`, `estRetailPriceFormatted` | brand-new retail estimate, when disclosed | | `discountText`, `discountPercent` | only present when the item is on sale — in practice rare/absent, since the browse-listing API this actor reads does not reliably expose a markdown signal (see `onSaleOnly` note under Input below) | | `images[]`, `imageUrl` | direct CDN URLs, not hotlink-protected | | `productUrl` | canonical `therealreal.com/products/...` URL | | `availability`, `quantity`, `obsessionCount`, `waitlisted`, `editorsPick`, `badge` | `badge` is the merchandising label text only (e.g. `"Good Value"`, `"New"`) | | `buyNowEligible` | `byUrl` only — whether the site offers an instant "Buy It Now" fast-checkout path for this item vs its normal add-to-bag flow | | `description`, `measurements[]`, `authenticationInfo`, `returnable`, `returnPolicyText`, `disclaimerText`, `categoryLabel`, `carbonSavedKg`, `waterSavedLiters` | `byUrl` only | | `valuationReportUrl` | `byUrl` only, watches — link to the item's real appraisal/valuation report page | | `availablePolicies[]` | `byUrl` only — `{name, priceUsd, sku}` optional add-on protection/warranty plans, when offered (e.g. watches) | | `glossaryTerms[]` | `byUrl` only — `{name, description}` item-specific terminology (e.g. watch complications), when the site discloses it | | `slug` | `byUrl` only — the product's URL slug | | `sizeGuide` | `byUrl` only — `{guideType: "table", columnHeaders[], rows[][]}` (a real size-conversion table, e.g. shoes' US/Italy/UK/France/Japan) or `{guideType: "document", description, downloadUrl}` (a downloadable PDF chart, e.g. rings), when the department offers one | | `measurementGuide` | `byUrl` only — `{imageUrl, measurements: [{label, description}]}` general how-to-measure diagram/instructions for the department, distinct from the item's own `measurements[]` | | `firstLookProduct` | `byUrl` only — present (`true`) only when the item is early-access-eligible for registered members | | `recordType: "product"`, `scrapedAt` | | ### Output — category taxonomy (`recordType: "category"`, mode=`discoverCategories`) | Field | Notes | |---|---| | `name` | Human-readable category/subcategory name | | `department` | Top-level department slug, e.g. `women` | | `categoryPath` | Path after the department, e.g. `handbags/totes` — absent for a top-level department node | | `depth` | `1` = department, `2` = category, `3` = subcategory | | `productCount` | Live count of items currently listed under this node | | `categoryUrl` | `https://www.therealreal.com/shop/[/]` | | `recordType`, `scrapedAt` | | ### Output — designer facet (`recordType: "designer"`, mode=`discoverDesigners`) | Field | Notes | |---|---| | `designerName` | Real designer/brand display name | | `designerSlug` | Derived slug — verified to resolve to real `byDesigner` results | | `designerId` | The RealReal's internal numeric designer ID | | `productCount` | Live count of items currently listed for this designer within the requested department/category scope | | `department` | The department this facet was scoped to | | `designerUrl` | `https://www.therealreal.com/designers/[/]` | | `recordType`, `scrapedAt` | | ### Input | Field | Type | Mode | Description | |---|---|---|---| | `mode` | select | – | `byCategory` / `byDesigner` / `byUrl` / `discoverCategories` / `discoverDesigners` | | `gender` | select | byCategory / discoverDesigners | Department: women / men / jewelry / watches / art / home / kids / beauty | | `categoryPath` | select | byCategory / discoverDesigners | Curated subcategory (50+ options) | | `customCategoryPath` | string | byCategory / discoverDesigners (override); discoverCategories (prefix filter) | Free-text override, e.g. `clothing/dresses/maxi`. Each `/`-separated segment is sanitized independently: a segment containing anything other than lowercase letters/digits/hyphens (path-traversal `..`, HTML/script injection, unicode/accented text, stray spaces, etc.) is silently dropped rather than rejecting the whole path — e.g. `clothing/drésses` (accented typo) normalizes to just `clothing`, browsing/listing the whole Clothing department rather than 0 results. This is deliberate (round-2 QA: a rejected-whole-path approach let a `../../etc/passwd`-style segment reach the upstream URL builder and 422); it means a badly-typed subcategory silently widens to its nearest valid ancestor instead of failing — copy the exact slug from `discoverCategories` output or a real therealreal.com URL to avoid this. | | `designerSlug` | string | byDesigner | e.g. `chanel`, `gucci`, `hermes` | | `designerGender` | select | byDesigner | Restrict to a department | | `productUrls` | array | byUrl | Full product URLs | | `minPrice` / `maxPrice` | int | all | USD | | `condition` | array (select) | all | As Is / Fair / Good / Very Good / Excellent / Pristine | | `color` | select | all | 19 curated colors | | `size` | string | all | Exact size match (case-insensitive), free text since the vocabulary is department-specific (e.g. `M`, `8.5`, `6`, `36mm`) | | `material` | string | all | Substring match against `material` (case-insensitive), free text since the vocabulary is department-specific (e.g. `Gold` matches `Yellow Gold`/`White Gold`/`Rose Gold`, `Leather`, `Silk`, `Cashmere`). Not populated on every item/department — verified live 2026-07-26: reliably populated on jewelry (`METAL_TYPE`, 120/120 sampled), absent on the sampled `clothing/dresses`/`clothing/coats` listings. | | `movementType` | select | all | Watches only — Automatic / Quartz / Manual / Co-Axial Escapement Automatic / Spring Drive / SolarBeat™ | | `caseMaterial` | select | all | Watches only — Yellow Gold / Rose Gold / White Gold / Platinum / Silver / Stainless Steel / Stainless Steel and Gold / Titanium / Ceramic / Other | | `onSaleOnly` | bool | all | Only discounted items. **Known limitation** (confirmed live, QA round after feature-expansion pass 3): therealreal.com's own browse-listing GraphQL query never populates a real discount/markdown signal — `price.discount` is `null` and `price.original == price.final` for every item returned, even on the site's own literal `sale` merchandising collection (0/120 sampled items had a genuine markdown across `women/sale`, `men/sale`, and ordinary categories). This means `onSaleOnly=true` may legitimately return 0 records on any category/designer; the run's status message calls this out explicitly rather than suggesting you loosen your filters. | | `sortBy` | select | all | newest / priceAsc / priceDesc / mostObsessed | | `maxItems` | int | all | 1–500, default 30 | #### Example: Chanel handbags under $3,000 ```json { "mode": "byDesigner", "designerSlug": "chanel", "designerGender": "women", "maxPrice": 3000, "maxItems": 50 } ```` #### Example: pristine-condition women's dresses, sorted cheapest first ```json { "mode": "byCategory", "gender": "women", "categoryPath": "clothing/dresses", "condition": ["Pristine"], "sortBy": "priceAsc", "maxItems": 50 } ``` #### Example: discover the real category taxonomy under "handbags" ```json { "mode": "discoverCategories", "customCategoryPath": "handbags", "maxItems": 100 } ``` #### Example: discover the top designers for women's shoes ```json { "mode": "discoverDesigners", "gender": "women", "categoryPath": "shoes", "maxItems": 50 } ``` ### Use cases - **Resale price benchmarking** — track live prices, discounts, and estimated retail value for designer items across categories or a specific brand. - **Inventory monitoring for resellers** — watch a designer's or category's live listings (`obsessionCount`, `availability`, `badge`) to spot fast-moving or newly-listed pieces. - **Market research on luxury resale trends** — analyze condition, size, and color distribution across a department or designer's current catalog. - **Sustainability reporting** — aggregate `carbonSavedKg`/`waterSavedLiters` from `byUrl` fetches to quantify the environmental impact of resale. - **Catalog/taxonomy mapping** — use `discoverCategories` and `discoverDesigners` to build a complete, accurate picker UI without guessing slugs. - **Authentication & provenance research** — pull `authenticationInfo` and full item detail for due-diligence on a specific listed piece. ### FAQ **Is this affiliated with The RealReal?** No. This is an independent third-party actor that reads The RealReal's own publicly rendered pages. It is not affiliated with, endorsed by, or supported by The RealReal, Inc. **Why does this actor fetch through a reader-proxy instead of therealreal.com directly?** therealreal.com is protected by PerimeterX, which blocks direct and TLS-impersonated automated requests alike (see "Data Source & anti-bot escalation" below for the full evidence). Routing through a public server-side-rendering reader-proxy reliably renders the site's real, live data without requiring cookies, login, or a paid residential proxy. **Why do some categories or `byUrl` fetches return 0 records?** A small number of high-traffic pages (the Handbags department, bare aggregate category pages, and individual product-detail pages) are currently subject to a tighter PerimeterX block than the rest of the site. The actor retries and fails soft with a clear status message rather than guessing or fabricating data — treat those paths as best-effort and prefer a specific subcategory (e.g. `clothing/dresses`, `shoes/sneakers`) or `byDesigner` for guaranteed-reliable results. **Why does `onSaleOnly=true` sometimes return 0 records?** The RealReal's own browse-listing data does not currently expose a genuine discount/markdown signal on any sampled category, including its own `sale` merchandising collection — this is an upstream data-availability limitation, not a filter bug. `originalPriceUsd`/`discountPercent` are still populated correctly whenever the source does disclose a real discount. **Is there a live keyword-search mode?** No. The RealReal's search results are rendered client-side after the page loads, so there's no server-rendered snapshot to read. Use `byCategory` or `byDesigner` (and `discoverCategories`/`discoverDesigners` to find real values) instead. **How fresh is the data?** Every fetch reads The RealReal's live, currently-listed inventory at run time — prices, availability, and product counts reflect the site as of the moment the actor runs. **Does this actor require login, cookies, or a paid proxy?** No. It runs on the Apify free plan with no login, no cookies, and no paid proxy of any kind. ### Data Source & anti-bot escalation therealreal.com is protected by **PerimeterX**, which serves a `px-captcha` "Access to this page has been denied" 403 on essentially every automated request. This was verified through a genuine escalation ladder before falling back to any workaround: 1. **Tier 2 — curl\_cffi with browser TLS impersonation.** Requests to the homepage, category, and product pages with `chrome131`, `chrome124`, and `safari184` impersonation plus a full realistic header set (Accept-Language, sec-ch-ua, sec-fetch-\*, etc.) all returned **HTTP 403** with an identical PerimeterX px-captcha body, regardless of impersonated browser. 2. **Tier 3 — headless Playwright with stealth.** Chromium launched headless with `--disable-blink-features=AutomationControlled` and `playwright_stealth` applied, hitting the real homepage, also returned **HTTP 403** with the same px-captcha page — even from a non-datacenter (residential ISP) source IP, which is a stronger signal than Apify's own datacenter/AUTO-proxy exits would produce. 3. **Reader-proxy fallback (r.jina.ai).** Both direct tiers genuinely failed, so per the project's anti-bot decision tree a neutral third-party mirror was tried: [r.jina.ai](https://r.jina.ai), a public server-side-rendering reader-proxy. It reliably renders therealreal.com's real, live Next.js pages and returns the same `__NEXT_DATA__` GraphQL payload the site's own React frontend consumes — including full product listings, prices, images, and (on product-detail pages) condition, size, measurements, and authentication copy. This actor fetches every page **through r.jina.ai**, not the origin directly. **This is a documented, third-party architectural dependency**, not something Apify or this project operates or guarantees: - If r.jina.ai is unavailable or rate-limited, this actor will fail soft (0 records + a clear `Actor.set_status_message`) rather than crash. - Every fetch is retried (up to 4 attempts, exponential backoff, rotating TLS-impersonation profile) before giving up on a single page. - A **content-based quality-retry** check additionally verifies the *actual returned items* (not just the echoed request) match what was requested — e.g. for `byCategory`, that a majority of returned products' own URLs fall under the requested department/category; for `byDesigner`, that a majority of returned products' brand slugifies to the requested designer. This was added after cloud verification caught a real upstream bug: the site's echoed GraphQL `variables` correctly reflect the requested taxon/designer even when the underlying query silently falls back to a generic, unfiltered item set (reproduced with both an invalid sub-category and a nonexistent designer slug) — so the echoed `variables` alone are not trustworthy proof of filtering. If a page never returns genuinely matching data after all retries, that page is skipped (0 records + `set_status_message`) rather than shipping wrong-category records. See `edges_match_category` / `edges_match_designer` in `src/helpers.py`. - Certain high-traffic, **bare/aggregate** category pages — e.g. women's **Handbags** (`women/handbags`) and the bare **Clothing**/**Accessories** department pages (`women/clothing`, `women/accessories`, no subcategory) — were observed to be hard-blocked by PerimeterX consistently more often than specific subcategory pages, likely because they're the site's highest-traffic pages. Re-confirmed live (2026-07-25, QA round 3): `categoryPath=clothing` (no subcategory) reproducibly returned 0 records (consistent `px-captcha` payload, ~5.7 KB, via the reader-proxy) on 2 separate attempts a few minutes apart, while `categoryPath=clothing/dresses` and every other specific subcategory tested rendered reliably (including a clean 500/500-item `maxItems` stress run). **Update (2026-07-26, round-4 QA):** the block has since widened to cover the entire **Handbags** department, including its named subcategories (`handbags/totes`, `handbags/shoulder-bags`, `handbags/crossbody-bags`, `handbags/clutches` all reproducibly returned 0 records / `px-captcha`, verified both through the actor and via a bare reader-proxy probe outside the actor entirely, ruling out an actor-code cause) — this is a change from the state recorded in QA round 3, where handbags subcategories rendered reliably; PerimeterX's protection on this specific high-value department has evidently tightened since. `clothing/dresses`, `shoes`, and the bare `women` department page were re-confirmed reliable in the same probe session, so this is category-specific, not a general/session-wide block. The actor still attempts bare/aggregate and Handbags-department pages with full retry logic; if a page fails, `Actor.set_status_message` reports this clearly rather than emitting 0 records silently. **Recommendation:** pick a specific subcategory outside the Handbags department (e.g. `clothing/dresses`, `shoes/sneakers`) for reliable results; treat any Handbags path (including named subcategories) as best-effort until PerimeterX's stance on that department changes again. - **`byUrl` (product-detail) fetches are currently blocked** (re-verified 2026-07-25, adversarial QA round 1): PerimeterX now serves the `px-captcha` block page through r.jina.ai for individual `/products/...` detail pages consistently — reproduced independently on 3 separate fresh, real, currently-listed product URLs (including URLs pulled live from this actor's own `byCategory` output moments earlier) both through the actor itself and via a bare `curl` against `r.jina.ai` outside the actor entirely, ruling out an actor-code cause. `byCategory` and `byDesigner` listing pages are unaffected and continue to render reliably through the same reader-proxy path. This is a change from the state recorded in earlier verification rounds (see the Round 4b table below, where a `byUrl` call did return 1 real record) — PerimeterX's product-detail-page policy has evidently tightened since. The actor already handles this correctly (fails soft: 0 records + `"No products resolved from the given URLs."` status message, no crash, no timeout), so no code change was needed; `byUrl` should currently be treated as best-effort like the Handbags category, not as reliable as `byCategory`/`byDesigner`. - Free-text keyword search is **not supported** in this version: The RealReal's `/shop/search?q=...` route does not apply the query server-side in its initial render (the real search executes as a client-side call after hydration, which is invisible to a server-rendered snapshot), and no public GET-based search API endpoint was found. Category browse and designer browse cover the vast majority of realistic use cases; a future version could add search if the site exposes a stable API for it. #### Feature-surface expansion (2026-07-26, 5th pass) — investigation evidence A further pass re-checked whether an interactive UI element (sort control, "Refine Results" sidebar) had gone unreverse-engineered. Findings: **Added:** - `discoverCategories` / `discoverDesigners` modes — every `byCategory`/ `byDesigner` listing fetch's `serverResult.data.products` payload already carries a `aggregations` array: this is the exact data that powers the site's own "Refine Results" sidebar (Categories, Designers, Condition, Color, sizes, etc.), previously read only for `edges`/`pageInfo` and never for `aggregations`. Two facets are genuinely new, zero-extra-cost feature surface (same fetch already being made): the real, complete, cross- department **category tree** (verified 3 levels deep with live product counts) and up to 200 real **designer names per department/category scope** (with live product counts and internal numeric IDs) — both confirmed live 2026-07-26. A designer name's derived slug was spot-checked against real `byDesigner` fetches: `Acne Studios` → `acne-studios` → 9,095 items; `3.1 Phillip Lim` → `3-1-phillip-lim` → 8,487 items — both real, matching counts, not fabricated. - `beauty` added to the `gender` department enum — discovered as an 8th top-level department in the same `aggregations` "Categories" facet (not previously listed); confirmed live via `shop/beauty` (HTTP 200, 6 real listed items — a genuinely small but real department, honestly small rather than silently dropped). **Investigated and rejected:** - **Server-side sort control** — the listing GraphQL response's `sortByOptions` field reveals the upstream *does* support 5 real sort values (`NEWEST`, `LOWEST_PRICE`, `HIGHEST_PRICE`, `SOLD`, `MOST_OBSESSED`), one more (`SOLD`/"Sold Items First") than this actor's existing local `sortBy` reorder. However, no URL query parameter (tried `sortBy`, `sort`, `orderBy`, `sort_by`, `sortByValue`, both upper/lower- cased values) was found that changes `sortByOptions.selected` away from `NEWEST` on the server-rendered response — the sort control appears to be driven by a client-side GraphQL variable set after hydration, which the reader-proxy's static-render snapshot cannot reach (same class of limitation as the already-documented keyword-search rejection above). `sortBy` therefore remains a local post-fetch reorder of the already- fetched maxItems-worth of newest-first records, not a real upstream sort parameter, and `SOLD` was not added (no reachable way to request it). - **Combined category+designer browse query variable** — investigated whether a `where.booleans`/`where.buckets` GraphQL variable could be passed via URL to filter a category page to one designer (or vice versa) in a single fetch; no such query-string mechanism was found through the static-render path (same client-side-only limitation as sort, above). `discoverDesigners` mode already lets a caller find the right slug to then run as a *separate* `byDesigner` fetch (with `designerGender` for department scoping) as a practical two-step workaround. #### Feature-surface expansion (2026-07) — investigation evidence A follow-up pass re-verified the full upstream surface through the reader-proxy and checked whether direct fetch had become viable. Findings: **Added:** - `sale` and `new-arrivals` curated `categoryPath` options — confirmed via reader-proxy fetch of `shop/women/sale` (HTTP 200, 1.8 MB payload, 120 real product edges) and `shop/women/new-arrivals` / `shop/new-arrivals` (HTTP 200, ~1.8 MB, 120 real edges). These are reachable today through the existing `customCategoryPath` mechanism too; adding them to the curated dropdown just makes them discoverable without needing the free-text override. - `returnPolicyText` — `product.returnPolicy.description` (e.g. *"This item can be returned for credit card refund. Return Authorization requests must be made within 14 days..."*), confirmed present on a real fetched product detail page (SKU `WEX127910`) but not previously captured (only the `returnable` boolean was). - `disclaimerText` — `product.disclaimers[].message` (e.g. *"Coupons and discounts are not available for this product."*), confirmed present on the same real fetch. - `categoryLabel` — `product.category.label` (e.g. `"Women's Fashion & Accessories"`), a human-readable top-level category name distinct from the existing `categoryBreadcrumb`. **Investigated and rejected:** - **Seller/consignor info** — `product.representative` and `product.storeContactInfo` are both `null` on every real product detail page fetched (SKU `WEX127910` dress, SKU `CHA1467696` Chanel boots — 2 different departments). The RealReal does not expose per-item consignor identity publicly (consistent with its consignment-anonymity model); no field to add. - **Price-drop / promotion history** — `product.promotion` and `product.valuationReportUrl` are `null` on every real fetch above. At the listing-GraphQL level, `price.original` equaled `price.final` (no diff) and `price.discount` was `null` across 240 sampled listing items spanning 2 categories (`women/clothing/dresses`, `women/shoes/sneakers`) *and* the dedicated `shop/women/sale` listing (120 items, still 0 with a real discount). The existing `originalPriceUsd`/`discountPercent` fields already handle a discount correctly when present (per the shipped omit-empty contract) — there is simply no live discounted inventory to observe right now, and no separate price-history field exists upstream to add. - **"Similar Items" / "You may also like"** — confirmed present as a UI section (`data-testid="similar-items-carousel"`) on product detail pages, but its `
` is server-rendered **empty**; the carousel is populated by a client-side XHR call after hydration, which the reader-proxy's static HTML/`__NEXT_DATA__` snapshot cannot see. No reliable server-rendered data source for this exists. - **Item condition report detail** — ~~previously marked "already fully captured"~~ **correction (2026-07-27 pass): this was wrong.** A fresh key-by-key diff of 3 real product-detail pages found the site's own `condition`-type attribute carries a real, distinct free-text note (e.g. *"No visible signs of wear"*, *"Minor scratches throughout metal; Minor wear at strap"*) that was never being extracted — not because the field didn't exist, but because of a real dead-code bug (see "Bug fix" below) in the attribute-type lookup that silently failed on product-detail-page attribute shapes. Now shipped as `conditionNotes`. **Bug fix (2026-07-27 pass) — dead-code attribute-type mismatch on `byUrl`:** Listing pages (`byCategory`/`byDesigner`) encode compound GraphQL attribute types as `SCREAMING_SNAKE_CASE` (e.g. `CLOTHING_SIZE`, `RING_SIZE`, `CASE_MATERIAL`), but product-detail pages (`byUrl`) encode the *exact same* attributes as `lower-hyphen-case` (e.g. `clothing-size`, `ring-size`, `case-material`) — confirmed live against 3 real product-detail pages spanning clothing/jewelry/watches. The attribute-type comparison only normalized case, not the hyphen-vs-underscore difference, so every compound (multi-word) attribute type — `size` and every jewelry/watch-specific field — silently extracted as absent on every single `byUrl` record, site-wide, since those fields were introduced. Single-word types (`COLOR`, `CONDITION`, `FABRIC`, `GENDER`, `MOVEMENT`) happened to match by coincidence, which is why this went unnoticed across 13 prior expansion passes. Fixed by normalizing both hyphens and underscores before comparing (`_norm_attr_type` in `src/helpers.py`); added regression tests covering the hyphenated shape for `_attr_first`/`_attr_all`/`_size_value`/`_material_value` and an end-to-end `build_detail_record` test. - **Direct fetch (tiered fallback) for category listings or item detail** — re-tested `curl_cffi` against both a category URL (`shop/women/clothing/dresses`) and a product URL, with `chrome124`, `safari17_0`, and `chrome131` impersonation plus a full realistic header set (`Accept`, `Accept-Language`, `sec-ch-ua`, `sec-fetch-dest/mode/site/user`, `upgrade-insecure-requests`). **All 6 combinations returned HTTP 403 with the identical PerimeterX px-captcha body** (`"Access to this page has been denied"`, 5703 bytes). No route is currently fetchable directly; the reader-proxy-always architecture is unchanged. - **Designer page reliability note** — during this pass, the *bare* `/designers/` URL (no department segment) was observed hard-blocked (px-captcha) on 4/4 consecutive attempts across 4 different designer slugs, while the department-qualified `/designers//` URL succeeded normally. This actor's `designerGender` input already defaults to `women` (always populated in `build_designer_url`), so the shipped default path is unaffected; this is noted here as an observed reliability characteristic of the bare aggregate page (similar to the already-documented Handbags category), not a regression. ### Cloud Verification All 7 rounds of the project's standard cloud-verification cadence were run on Apify actor `omnipotent_org/therealreal-scraper` (Actor ID `MzsAttKd5TTQCldB4`), a QA dummy account — never `crawlerbros`. Every run below was re-confirmed live against the Apify platform API (`GET /v2/acts/{actorId}/runs` and `GET /v2/datasets/{id}`), not recalled from memory. All 20 runs are `SUCCEEDED`. | Round | Purpose | Run ID | Dataset ID | Items | |---|---|---|---|---| | 1 | Default prefill (`byCategory` / women / clothing/dresses) | `1j23jG5kIo0c5Hvkp` | `C9aMbbjdX9GJV6HxE` | 20 | | 2 | Non-default mode + filter (`byDesigner` chanel/women) | `xNVT4I3vEPkd3Z7tn` | `3n9hg3cJX3v9rhpU2` | 25 | | 3 | URL accessibility (sampled from Round 1/2 datasets, see below) | – | – | – | | 4a | Boundary: `maxItems=1` | `Gi5M8CgIjPsXhDPnp` | `bHoeezaNsDIaWq6tS` | 1 | | 4a | Boundary: `maxItems=500` (department-wide) | `26j96IgeBtRXgyfMp` | `1IxF8IsHe5u14axyu` | 500 | | 4a | All filters combined (price/condition/department) | `F5JMHNq1vVGGkFIpF` | `vkW6PxPyQGWe8g1WO` | 30 | | 4b | Edge: inverted price range (`minPrice=900 > maxPrice=10`) | `6KwegVrSuuZq09dXt` | `qqnsgitJaoWQCZvcU` | 0 (clean, no crash) | | 4b | Edge: bogus designer slug (`zzz-not-a-real-designer-xyz`) | `ngjZBB6bgGynrCTN1` | `hQEF8O9fmKn3uZUaf` | 0 (correctly rejected by content-based quality-check — see below) | | 4b | Edge: unicode designer slug (`シャネル`) | `VpganonuoGElO5E7T` | `G06Kc95P3zdQMLauT` | 0 (clean, no `UnicodeEncodeError`) | | 4b | Edge: `byUrl` with 1 malformed + 1 non-product + 1 valid URL | `Pzzgl1KpTYlEj44VO` | `YYC6NjHUO1CMOXIL8` | 1 (invalid entries skipped, no crash) | | 5 | Repeat run 1/3 (same input) | `uQnsDuYg7H6C81qNI` | `Tq2beTlfYUiMPaePb` | 25 | | 5 | Repeat run 2/3 | `5jxjKNlnLz4WSoQHk` | `3bRmL4x5yPirwlDyb` | 25 | | 5 | Repeat run 3/3 | `G56NhWM4pAXaGgsCc` | `MBY3S2teqf1dRSaNo` | 25 (0% variance across all 3) | | 6 | Combined filters (price + color + sort) | `9F0Zanzs1YzZBPgUU` | `nwPC6Mb48b8TfCCwT` | 30 | | 6 | Multi-URL batch with 1 intentional duplicate | `UzZ0szx78fCn1nNRP` | `d5hUpToTRf8a7sXvU` | 3 (deduped from 4 input URLs) | | 7a | International/non-default department (`jewelry/rings`) | `abexA7u0UFsjVggjw` | `8imF2ocjZyhiVbtmU` | 15 | | 7b | Pagination exact: `maxItems=120` (= 1 page) | `jPS7qreCyHCIkqVYi` | `LSJBfcy2I99kCveMT` | 120 | | 7b | Pagination exact: `maxItems=130` (spans 2 pages) | `mUeTNAGPUbCq5UwAj` | `JvH1pJYkzy67YwSaO` | 130 | | 7c | Long-running: `maxItems=400`, full department | `tahlEWL3PfDK9b1yc` | `z9nX6C813Jt2VClJL` | 400 (completed in ~41s, no timeout, no slowdown) | #### Round 1 sample record (default prefill, `C9aMbbjdX9GJV6HxE`) ```json { "productId": "53030673", "sku": "OSC282427", "name": "V-Neck Knee-Length Dress", "brand": "Oscar de la Renta", "department": "women", "categoryPath": "clothing/dresses", "condition": "Excellent", "size": "S", "color": "Blue", "priceUsd": 235, "priceFormatted": "$235.00", "imageUrl": "https://product-images.therealreal.com/OSC282427_1_enlarged.jpg", "productUrl": "https://www.therealreal.com/products/women/clothing/dresses/oscar-de-la-renta-halterneck-knee-length-dress-vkmq9", "availability": "AVAILABLE", "quantity": 1, "obsessionCount": 7, "recordType": "product", "scrapedAt": "2026-07-24T18:26:12.479548+00:00" } ``` #### Round 2 sample record (`byDesigner` chanel/women, `3n9hg3cJX3v9rhpU2`) — confirms filter honored (all 25 records are `brand: "Chanel"`, `gender: "Women"`) ```json { "productId": "53211495", "sku": "CHA1467696", "name": "2015 Interlocking CC Logo Boots", "brand": "Chanel", "department": "women", "categoryPath": "shoes/boots", "condition": "Fair", "size": "IT 37.5", "priceUsd": 265, "estRetailPriceUsd": 1150, "productUrl": "https://www.therealreal.com/products/women/shoes/boots/chanel-2015-interlocking-cc-logo-boots-voi93", "recordType": "product", "scrapedAt": "2026-07-24T18:26:57.233195+00:00" } ``` #### Round 4b sample record (`byUrl`, full detail fields, `YYC6NjHUO1CMOXIL8`) ```json { "productId": "53448685", "sku": "WEX127910", "name": "Skirt Set w/ Tags", "brand": "Alexis", "condition": "Pristine", "categoryBreadcrumb": ["Skirt Sets", "Suits and Sets", "Clothing", "Women"], "priceUsd": 335, "measurements": [{"label": "Bust", "value": "31.25\""}, {"label": "Waist", "value": "28.25\""}], "authenticationInfo": "We authenticate every item with a rigorous process overseen by experts. ...", "carbonSavedKg": 1.24, "waterSavedLiters": 4.11, "returnable": true, "recordType": "product" } ``` #### Round 3 — URL accessibility (re-verified via clean `curl -ILSs`, no Referer/cookies) - `https://product-images.therealreal.com/OSC282427_1_enlarged.jpg` → `200 image/jpeg` - `https://product-images.therealreal.com/CHA1467696_1_enlarged.jpg` → `200 image/jpeg` - `https://product-images.therealreal.com/GUC2102612_1_enlarged.jpg` (sampled from the Round 7c 400-item run) → `200 image/jpeg` - `productUrl` fields (e.g. `.../products/women/shoes/boots/chanel-...`) → `403` from a plain `curl`, as documented above (PerimeterX; loads normally in a real browser). #### Local test suite `python -m pytest tests/ -q` → **320 passed**, 0 failed (re-run and re-confirmed after the content-based quality-check fix above). #### Bug found and fixed during cloud verification Round 4b's bogus-designer-slug test (`zzz-not-a-real-designer-xyz`) initially returned 10 unrelated records instead of 0 — root cause: the site's GraphQL `variables` echo the requested (bogus) slug even when it silently falls back to a generic, unfiltered listing. Fixed by adding `edges_match_designer` / `edges_match_category` (content-based verification against the *returned* items, not the echoed request) and re-verified live: the same input now correctly returns 0 records with a clear `set_status_message` (run `ngjZBB6bgGynrCTN1`, dataset `hQEF8O9fmKn3uZUaf`). ### Notes - No login, cookies, or paid proxy required — the actor works on the Apify free plan. - Product images are served from `product-images.therealreal.com`, which is not hotlink-protected (verified via a clean `curl -ILSs`, no Referer/cookies needed). - `productUrl` values point at therealreal.com itself; loading them directly in a plain HTTP client (e.g. `curl`) will hit the same PerimeterX wall described above — they load normally in a real browser. # Actor input Schema ## `mode` (type: `string`): What to fetch. `byCategory`/`byDesigner`/`byUrl` fetch real product listings/detail. `discoverCategories` (reliable, one cheap fetch) lists therealreal.com's own complete, real category taxonomy tree (department -> category -> subcategory) straight from the site's own "Refine Results" facet data, each with a live product count -- use it to find real `categoryPath`/`customCategoryPath` values beyond the curated dropdown. `discoverDesigners` (reliable, one cheap fetch) lists up to 200 real designer/brand names (with live product counts) for a department/category, straight from the same facet data -- use it to find real `designerSlug` values instead of guessing. ## `gender` (type: `string`): Top-level department to browse. ## `categoryPath` (type: `string`): A curated common category path. Leave as `(department only)` to browse the whole department, or pick a subcategory. For a category not listed here, use `Custom category path` below instead (overrides this field). ## `customCategoryPath` (type: `string`): Advanced: any taxonomy path segment(s) after the department, e.g. `clothing/dresses/maxi` or `shoes/boots/ankle-boots`. Copy from a therealreal.com/shop// URL. Overrides the Category dropdown when set. For mode=discoverCategories, filters the taxonomy listing to entries whose category path starts with this value (leave empty to list the entire tree). ## `designerSlug` (type: `string`): The RealReal designer slug, e.g. `chanel`, `gucci`, `hermes`, `louis-vuitton`, `cartier`, `christian-dior`. Find it in a therealreal.com/designers/ URL. ## `designerGender` (type: `string`): Restrict the designer's items to a department. ## `productUrls` (type: `array`): Full therealreal.com/products/... URLs to fetch complete detail for (price, condition, size, measurements, authentication info, images). ## `minPrice` (type: `integer`): Drop items priced below this (USD). ## `maxPrice` (type: `integer`): Drop items priced above this (USD). ## `condition` (type: `array`): Only include items in these conditions. Leave empty for all conditions. ## `color` (type: `string`): Only include items in this color. ## `size` (type: `string`): Only include items with exactly this size (case-insensitive). Free text because the size vocabulary is department-specific: clothing sizes (e.g. `S`, `M`, `FR38`), shoe sizes (e.g. `8.5`), ring sizes (e.g. `6`), art sizes (e.g. `Large`), watch case diameters (e.g. `36mm`). Leave empty for all sizes. ## `material` (type: `string`): Only include items whose material/fabric contains this text (case-insensitive substring match, e.g. `Gold` matches `Yellow Gold`/`White Gold`/`Rose Gold`, `Leather` matches `Leather Trim`). Free text because the material vocabulary is department-specific and wide -- metal type for jewelry (`Yellow Gold`, `White Gold`, `Rose Gold`, `Platinum`, `Silver`), fabric/material for apparel/handbags (`Leather`, `Silk`, `Cashmere`, `Cotton`, `Suede`, `Denim`, `Wool`). Not populated on every item/department -- leave empty for no filtering. ## `movementType` (type: `string`): Only include watches with this movement type. Only populated on items in the Watches department. ## `caseMaterial` (type: `string`): Only include watches with this case material. Only populated on items in the Watches department. ## `onSaleOnly` (type: `boolean`): Only include items with a discount off the original price. ## `sortBy` (type: `string`): How to order emitted results (applied locally after fetching). ## `maxItems` (type: `integer`): Hard cap on emitted records. ## Actor input object example ```json { "mode": "byCategory", "gender": "women", "categoryPath": "clothing/dresses", "designerSlug": "chanel", "designerGender": "women", "productUrls": [ "https://www.therealreal.com/products/women/clothing/suits-and-sets/alexis-skirt-set-w-tags-vtl9p" ], "condition": [], "color": "", "size": "", "material": "", "movementType": "", "caseMaterial": "", "onSaleOnly": false, "sortBy": "newest", "maxItems": 20 } ``` # Actor output Schema ## `products` (type: `string`): Dataset containing all scraped products. # API You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup. ## JavaScript example ```javascript import { ApifyClient } from 'apify-client'; // Initialize the ApifyClient with your Apify API token // Replace the '' with your token const client = new ApifyClient({ token: '', }); // Prepare Actor input const input = { "mode": "byCategory", "gender": "women", "categoryPath": "clothing/dresses", "designerSlug": "chanel", "designerGender": "women", "productUrls": [ "https://www.therealreal.com/products/women/clothing/suits-and-sets/alexis-skirt-set-w-tags-vtl9p" ], "condition": [], "color": "", "size": "", "material": "", "movementType": "", "caseMaterial": "", "onSaleOnly": false, "sortBy": "newest", "maxItems": 20 }; // Run the Actor and wait for it to finish const run = await client.actor("crawlerbros/therealreal-scraper").call(input); // Fetch and print Actor results from the run's dataset (if any) console.log('Results from dataset'); console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`); const { items } = await client.dataset(run.defaultDatasetId).listItems(); items.forEach((item) => { console.dir(item); }); // 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs ``` ## Python example ```python from apify_client import ApifyClient # Initialize the ApifyClient with your Apify API token # Replace '' with your token. client = ApifyClient("") # Prepare the Actor input run_input = { "mode": "byCategory", "gender": "women", "categoryPath": "clothing/dresses", "designerSlug": "chanel", "designerGender": "women", "productUrls": ["https://www.therealreal.com/products/women/clothing/suits-and-sets/alexis-skirt-set-w-tags-vtl9p"], "condition": [], "color": "", "size": "", "material": "", "movementType": "", "caseMaterial": "", "onSaleOnly": False, "sortBy": "newest", "maxItems": 20, } # Run the Actor and wait for it to finish run = client.actor("crawlerbros/therealreal-scraper").call(run_input=run_input) # Fetch and print Actor results from the run's dataset (if there are any) print("💾 Check your data here: https://console.apify.com/storage/datasets/" + run["defaultDatasetId"]) for item in client.dataset(run["defaultDatasetId"]).iterate_items(): print(item) # 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start ``` ## CLI example ```bash echo '{ "mode": "byCategory", "gender": "women", "categoryPath": "clothing/dresses", "designerSlug": "chanel", "designerGender": "women", "productUrls": [ "https://www.therealreal.com/products/women/clothing/suits-and-sets/alexis-skirt-set-w-tags-vtl9p" ], "condition": [], "color": "", "size": "", "material": "", "movementType": "", "caseMaterial": "", "onSaleOnly": false, "sortBy": "newest", "maxItems": 20 }' | apify call crawlerbros/therealreal-scraper --silent --output-dataset ``` ## MCP server setup ```json { "mcpServers": { "apify": { "command": "npx", "args": [ "mcp-remote", "https://mcp.apify.com/?tools=crawlerbros/therealreal-scraper", "--header", "Authorization: Bearer " ] } } } ``` ## OpenAPI specification ```json { "openapi": "3.0.1", "info": { "title": "The RealReal Scraper", "description": "Scrape The RealReal - the largest online marketplace for authenticated luxury resale. Browse by category or designer, or fetch full product detail (price, condition, size, measurements, authentication info, images) by product URL.", "version": "1.0", "x-build-id": "q5Xsdy1MW7ywVVZBU" }, "servers": [ { "url": "https://api.apify.com/v2" } ], "paths": { "/acts/crawlerbros~therealreal-scraper/run-sync-get-dataset-items": { "post": { "operationId": "run-sync-get-dataset-items-crawlerbros-therealreal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for its completion, and returns Actor's dataset items in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } }, "/acts/crawlerbros~therealreal-scraper/runs": { "post": { "operationId": "runs-sync-crawlerbros-therealreal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor and returns information about the initiated run in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/runsResponseSchema" } } } } } } }, "/acts/crawlerbros~therealreal-scraper/run-sync": { "post": { "operationId": "run-sync-crawlerbros-therealreal-scraper", "x-openai-isConsequential": false, "summary": "Executes an Actor, waits for completion, and returns the OUTPUT from Key-value store in response.", "tags": [ "Run Actor" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/inputSchema" } } } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Enter your Apify token here" } ], "responses": { "200": { "description": "OK" } } } } }, "components": { "schemas": { "inputSchema": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "title": "Mode", "enum": [ "byCategory", "byDesigner", "byUrl", "discoverCategories", "discoverDesigners" ], "type": "string", "description": "What to fetch. `byCategory`/`byDesigner`/`byUrl` fetch real product listings/detail. `discoverCategories` (reliable, one cheap fetch) lists therealreal.com's own complete, real category taxonomy tree (department -> category -> subcategory) straight from the site's own \"Refine Results\" facet data, each with a live product count -- use it to find real `categoryPath`/`customCategoryPath` values beyond the curated dropdown. `discoverDesigners` (reliable, one cheap fetch) lists up to 200 real designer/brand names (with live product counts) for a department/category, straight from the same facet data -- use it to find real `designerSlug` values instead of guessing.", "default": "byCategory" }, "gender": { "title": "Department (mode=byCategory / discoverDesigners)", "enum": [ "women", "men", "jewelry", "watches", "art", "home", "kids", "beauty" ], "type": "string", "description": "Top-level department to browse.", "default": "women" }, "categoryPath": { "title": "Category (mode=byCategory / discoverDesigners)", "enum": [ "", "handbags", "handbags/shoulder-bags", "handbags/totes", "handbags/crossbody-bags", "handbags/clutches", "handbags/hobos", "handbags/satchels", "handbags/mini-bags", "clothing", "clothing/dresses", "clothing/dresses/cocktail", "clothing/dresses/evening", "clothing/coats", "clothing/jackets", "clothing/jeans", "clothing/tops", "clothing/skirts", "clothing/pants", "clothing/knitwear/sweaters", "clothing/suits-and-sets", "shoes", "shoes/boots", "shoes/pumps", "shoes/sandals", "shoes/sneakers", "shoes/flats", "accessories", "accessories/sunglasses", "accessories/scarves-and-shawls", "accessories/wallets", "accessories/belts", "accessories/hats", "outerwear", "suits", "t-shirts", "loafers", "bags", "bags/backpacks", "bags/briefcases", "bags/totes", "rings", "necklaces", "earrings", "bracelets", "brooches", "cufflinks", "pins", "paintings", "photographs", "prints", "drawings-and-works-on-paper", "mixed-media", "tabletop-and-kitchen", "decor-and-accessories", "bedding-and-bath", "collectibles", "girls", "boys", "baby-gear", "sale", "new-arrivals" ], "type": "string", "description": "A curated common category path. Leave as `(department only)` to browse the whole department, or pick a subcategory. For a category not listed here, use `Custom category path` below instead (overrides this field).", "default": "" }, "customCategoryPath": { "title": "Custom category path (mode=byCategory/discoverDesigners, overrides Category; mode=discoverCategories: prefix filter)", "type": "string", "description": "Advanced: any taxonomy path segment(s) after the department, e.g. `clothing/dresses/maxi` or `shoes/boots/ankle-boots`. Copy from a therealreal.com/shop// URL. Overrides the Category dropdown when set. For mode=discoverCategories, filters the taxonomy listing to entries whose category path starts with this value (leave empty to list the entire tree)." }, "designerSlug": { "title": "Designer slug (mode=byDesigner)", "type": "string", "description": "The RealReal designer slug, e.g. `chanel`, `gucci`, `hermes`, `louis-vuitton`, `cartier`, `christian-dior`. Find it in a therealreal.com/designers/ URL.", "default": "chanel" }, "designerGender": { "title": "Designer department (mode=byDesigner)", "enum": [ "women", "men", "jewelry", "watches" ], "type": "string", "description": "Restrict the designer's items to a department.", "default": "women" }, "productUrls": { "title": "Product URLs (mode=byUrl)", "type": "array", "description": "Full therealreal.com/products/... URLs to fetch complete detail for (price, condition, size, measurements, authentication info, images).", "default": [], "items": { "type": "string" } }, "minPrice": { "title": "Min price (USD)", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Drop items priced below this (USD)." }, "maxPrice": { "title": "Max price (USD)", "minimum": 0, "maximum": 1000000, "type": "integer", "description": "Drop items priced above this (USD)." }, "condition": { "title": "Condition", "type": "array", "description": "Only include items in these conditions. Leave empty for all conditions.", "items": { "type": "string", "enum": [ "As Is", "Fair", "Good", "Very Good", "Excellent", "Pristine" ], "enumTitles": [ "As Is", "Fair", "Good", "Very Good", "Excellent", "Pristine" ] }, "default": [] }, "color": { "title": "Color", "enum": [ "", "Black", "White", "Grey", "Silver", "Gold", "Metallic", "Brown", "Neutrals", "Blue", "Green", "Red", "Burgundy", "Pink", "Purple", "Yellow", "Orange", "Animal Print", "Pattern Prints", "Clear" ], "type": "string", "description": "Only include items in this color.", "default": "" }, "size": { "title": "Size", "type": "string", "description": "Only include items with exactly this size (case-insensitive). Free text because the size vocabulary is department-specific: clothing sizes (e.g. `S`, `M`, `FR38`), shoe sizes (e.g. `8.5`), ring sizes (e.g. `6`), art sizes (e.g. `Large`), watch case diameters (e.g. `36mm`). Leave empty for all sizes.", "default": "" }, "material": { "title": "Material", "type": "string", "description": "Only include items whose material/fabric contains this text (case-insensitive substring match, e.g. `Gold` matches `Yellow Gold`/`White Gold`/`Rose Gold`, `Leather` matches `Leather Trim`). Free text because the material vocabulary is department-specific and wide -- metal type for jewelry (`Yellow Gold`, `White Gold`, `Rose Gold`, `Platinum`, `Silver`), fabric/material for apparel/handbags (`Leather`, `Silk`, `Cashmere`, `Cotton`, `Suede`, `Denim`, `Wool`). Not populated on every item/department -- leave empty for no filtering.", "default": "" }, "movementType": { "title": "Movement type (watches)", "enum": [ "", "Automatic", "Quartz", "Manual", "Co-Axial Escapement Automatic", "Spring Drive", "SolarBeat™" ], "type": "string", "description": "Only include watches with this movement type. Only populated on items in the Watches department.", "default": "" }, "caseMaterial": { "title": "Case material (watches)", "enum": [ "", "Yellow Gold", "Rose Gold", "White Gold", "Platinum", "Silver", "Stainless Steel", "Stainless Steel and Gold", "Titanium", "Ceramic", "Other" ], "type": "string", "description": "Only include watches with this case material. Only populated on items in the Watches department.", "default": "" }, "onSaleOnly": { "title": "On sale only", "type": "boolean", "description": "Only include items with a discount off the original price.", "default": false }, "sortBy": { "title": "Sort order", "enum": [ "newest", "priceAsc", "priceDesc", "mostObsessed" ], "type": "string", "description": "How to order emitted results (applied locally after fetching).", "default": "newest" }, "maxItems": { "title": "Max items", "minimum": 1, "maximum": 500, "type": "integer", "description": "Hard cap on emitted records.", "default": 30 } } }, "runsResponseSchema": { "type": "object", "properties": { "data": { "type": "object", "properties": { "id": { "type": "string" }, "actId": { "type": "string" }, "userId": { "type": "string" }, "startedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "finishedAt": { "type": "string", "format": "date-time", "example": "2025-01-08T00:00:00.000Z" }, "status": { "type": "string", "example": "READY" }, "meta": { "type": "object", "properties": { "origin": { "type": "string", "example": "API" }, "userAgent": { "type": "string" } } }, "stats": { "type": "object", "properties": { "inputBodyLen": { "type": "integer", "example": 2000 }, "rebootCount": { "type": "integer", "example": 0 }, "restartCount": { "type": "integer", "example": 0 }, "resurrectCount": { "type": "integer", "example": 0 }, "computeUnits": { "type": "integer", "example": 0 } } }, "options": { "type": "object", "properties": { "build": { "type": "string", "example": "latest" }, "timeoutSecs": { "type": "integer", "example": 300 }, "memoryMbytes": { "type": "integer", "example": 1024 }, "diskMbytes": { "type": "integer", "example": 2048 } } }, "buildId": { "type": "string" }, "defaultKeyValueStoreId": { "type": "string" }, "defaultDatasetId": { "type": "string" }, "defaultRequestQueueId": { "type": "string" }, "buildNumber": { "type": "string", "example": "1.0.0" }, "containerUrl": { "type": "string" }, "usage": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "integer", "example": 1 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } }, "usageTotalUsd": { "type": "number", "example": 0.00005 }, "usageUsd": { "type": "object", "properties": { "ACTOR_COMPUTE_UNITS": { "type": "integer", "example": 0 }, "DATASET_READS": { "type": "integer", "example": 0 }, "DATASET_WRITES": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_READS": { "type": "integer", "example": 0 }, "KEY_VALUE_STORE_WRITES": { "type": "number", "example": 0.00005 }, "KEY_VALUE_STORE_LISTS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_READS": { "type": "integer", "example": 0 }, "REQUEST_QUEUE_WRITES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_INTERNAL_GBYTES": { "type": "integer", "example": 0 }, "DATA_TRANSFER_EXTERNAL_GBYTES": { "type": "integer", "example": 0 }, "PROXY_RESIDENTIAL_TRANSFER_GBYTES": { "type": "integer", "example": 0 }, "PROXY_SERPS": { "type": "integer", "example": 0 } } } } } } } } } } ```