# Grailed API scraper — curated menswear, streetwear & archive-fashion resale data from grailed.com: search listings with price/size/designer/category/condition filters, full listing detail (description, measurements, photos, seller), SOLD comps for price history, designer & seller storefront listings — no API key required

> Search Grailed listings by keyword + filters (designer, category, size, color, condition, department, strata, location, price band) with sorting and pagination. Returns live listings with price, size, condition, designer, photos and a seller summary. The catalog-discovery surface.
> ReefAPI engine `grailed` · 6 endpoints · clean JSON, no scraping or browsers to manage.

## How to call
- **Endpoint:** `POST https://api.reefapi.com/grailed/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 or blocked calls are free.
- **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, `Authorization: Bearer <key>`) and your assistant can call these actions directly.

## Endpoints

### POST /grailed/v1/search — 1 credit
Search Grailed listings by keyword + filters (designer, category, size, color, condition, department, strata, location, price band) with sorting and pagination. Returns live listings with price, size, condition, designer, photos and a seller summary. The catalog-discovery surface.

**Parameters:**
- `query` (string, optional) — Keywords to search for (give query and/or at least one filter — empty query + a filter browses that facet).
- `designer` (string, optional) — Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action.
- `category` (enum, optional) — Top-level category facet. [one of: tops, bottoms, outerwear, footwear, tailoring, accessories, womens_tops, womens_bottoms, womens_outerwear, womens_dresses, womens_footwear, womens_accessories, womens_bags_luggage, womens_jewelry]
- `category_path` (string, optional) — Advanced: exact sub-category path (e.g. 'outerwear.denim_jackets', 'footwear.hi_top_sneakers'). Copy from a listing's category_path.
- `department` (enum, optional) — Menswear or womenswear section. [one of: menswear, womenswear]
- `size` (string, optional) — Size facet (e.g. 'm', 's', 'us 10', '32'). Sizes are category specific — copy the exact value from a search result's `size`.
- `color` (enum, optional) — Primary color facet. [one of: black, white, gray, brown, beige, blue, green, red, purple, pink, yellow, orange, silver, gold, multi]
- `condition` (enum, optional) — Item condition. [one of: is_new, is_gently_used, is_used, is_worn, is_not_specified]
- `strata` (enum, optional) — Grailed market tier (curation level). [one of: grailed, hype, sartorial, basic]
- `location` (enum, optional) — Seller location region. [one of: United States, Canada, United Kingdom, Europe, Asia, Australia/NZ, Other]
- `price_from` (number, optional) — Only listings at or above this price (USD).
- `price_to` (number, optional) — Only listings at or below this price (USD).
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, newest, price_low, price_high, most_popular, recently_bumped]
- `page` (integer, optional, default 1) — Page number (Algolia serves up to 200 pages per query).
- `per_page` (integer, optional, default 40) — Results per page (1–100).

**Returns:** listings[]{id, title, url, price, currency, size, condition, condition_label, color, category, department, designers[], designer_names, strata, location, cover_photo, buy_now, make_offer, sold, seller{id, username, rating_average, rating_count}} + meta.pagination{page, has_more} + meta.total_results

**Example request body:**
```json
{
  "query": "stone island",
  "per_page": 10
}
```

### POST /grailed/v1/listing_detail — 1 credit
Full detail for one listing by `id` or `url`: title, description, price, size (pretty + exact), condition, color, category, all photos, measurements, traits, shipping table, designers, sold price, and a seller summary.

**Parameters:**
- `id` (string, optional) — Grailed listing id — the digits in the listing URL (grailed.com/listings/<id>-slug). Take it from search results. Provide id OR url.
- `url` (string, optional) — Full Grailed listing URL — alternative to id.

**Returns:** listing{id, title, url, description, price, currency, size, pretty_size, condition, condition_label, color, category, subcategory, designers[], styles, strata, buy_now, make_offer, photos[], measurements[]{name, value}, traits[], shipping, sold, sold_price, seller{id, username, rating_average, rating_count, total_bought_and_sold, trusted_seller}}

### POST /grailed/v1/sold_listings — 1 credit
Search SOLD listings (resale comps) by keyword + the same filters as search. Each result carries its sold_price and sold_at — the price-history / market-value moat for valuing menswear, streetwear and archive pieces.

**Parameters:**
- `query` (string, optional) — Keywords for the sold-comps search (give query and/or a filter).
- `designer` (string, optional) — Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action.
- `category` (enum, optional) — Top-level category facet. [one of: tops, bottoms, outerwear, footwear, tailoring, accessories, womens_tops, womens_bottoms, womens_outerwear, womens_dresses, womens_footwear, womens_accessories, womens_bags_luggage, womens_jewelry]
- `department` (enum, optional) — Menswear or womenswear section. [one of: menswear, womenswear]
- `size` (string, optional) — Size facet (e.g. 'm', 's', 'us 10', '32'). Sizes are category specific — copy the exact value from a search result's `size`.
- `color` (enum, optional) — Primary color facet. [one of: black, white, gray, brown, beige, blue, green, red, purple, pink, yellow, orange, silver, gold, multi]
- `condition` (enum, optional) — Item condition. [one of: is_new, is_gently_used, is_used, is_worn, is_not_specified]
- `strata` (enum, optional) — Grailed market tier (curation level). [one of: grailed, hype, sartorial, basic]
- `price_from` (number, optional) — Only listings at or above this price (USD).
- `price_to` (number, optional) — Only listings at or below this price (USD).
- `sort` (enum, optional, default "newest") — Sold-comp ordering. [one of: newest, relevance, price_high, price_low]
- `page` (integer, optional, default 1) — Page number (Algolia serves up to 200 pages per query).
- `per_page` (integer, optional, default 40) — Results per page (1–100).

**Returns:** listings[]{id, title, url, price, sold_price, sold_at, size, condition, color, designers[], department, cover_photo, seller{username, rating_average}} + meta.pagination + meta.total_results

**Example request body:**
```json
{
  "query": "supreme",
  "per_page": 5
}
```

### POST /grailed/v1/seller_listings — 1 credit
All active listings from one seller's storefront by `seller_id`. Same listing shape as search; paginated. Resolve a seller_id from any search/detail result's seller.id.

**Parameters:**
- `seller_id` (string, required) — Grailed seller (user) id — take it from a listing's seller.id.
- `query` (string, optional) — Optional keyword to search within this seller's items.
- `category` (enum, optional) — Top-level category facet. [one of: tops, bottoms, outerwear, footwear, tailoring, accessories, womens_tops, womens_bottoms, womens_outerwear, womens_dresses, womens_footwear, womens_accessories, womens_bags_luggage, womens_jewelry]
- `designer` (string, optional) — Filter to one designer/brand by its EXACT Grailed name (e.g. 'Stone Island', 'Rick Owens', 'Supreme'). Resolve the exact name with the `designers` action.
- `sort` (enum, optional, default "relevance") — Result ordering. [one of: relevance, newest, price_low, price_high, most_popular, recently_bumped]
- `page` (integer, optional, default 1) — Page number (Algolia serves up to 200 pages per query).
- `per_page` (integer, optional, default 40) — Results per page (1–100).

**Returns:** listings[] (search shape) + seller{id, username} + meta.pagination + meta.total_results

### POST /grailed/v1/designers — 1 credit
Search Grailed's designer/brand directory by name → id, slug, listings_count, logo and departments. Use the returned exact `name` to filter search/sold_listings by designer, and the `slug` for the `designer_detail` action.

**Parameters:**
- `query` (string, required) — Designer/brand name (or part of it) to look up.
- `page` (integer, optional, default 1) — Page number (Algolia serves up to 200 pages per query).
- `per_page` (integer, optional, default 40) — Results per page (1–100).

**Returns:** designers[]{id, name, slug, url, listings_count, logo_url, departments[]} + meta.pagination

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

### POST /grailed/v1/designer_detail — 1 credit
Designer/brand profile by `slug`: id, title, description, follower count and the exact name to use as a designer filter.

**Parameters:**
- `slug` (string, required) — Designer slug from a designer URL (grailed.com/designers/<slug>) or the `designers` action.

**Returns:** designer{id, slug, name, description, follower_count, favorites_count, hero_url, thumbnail_url, url}

**Example request body:**
```json
{
  "slug": "stone-island"
}
```

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