# Grailed Item Search API Documentation

Grailed Item Search API Documentation Search Grailed listings for sale or sold. Every item has the id, url, title, designers, category path, department, size, colour, condition, price as a number with currency, price drops with the original price and discount, sold flag, sold date and sold price, location, shipping prices by region, cover photo, photo count, likes, the number of measurements, a seller summary with rating, and the listing dates. Set status to sold to read sold items with the price they sold for. Filters are enforced on every returned item: a designer filter returns that designer only, and the size, condition, location, category and price filters hold for every row. meta.filtered_out counts items that were removed by this check. Grailed returns at most 1000 results per search, so page 25 is the last page: narrow the search with filters to go deeper. Each page holds up to 40 items. For the full description, all photos and measurements of one item, call the listing endpoint. Cost: 1 credit per request, only for successful requests. - **Documentation:** [https://scrappa.co/docs/grailed-api/grailed_search](https://scrappa.co/docs/grailed-api/grailed_search) - **API group:** Grailed API - **Endpoint:** `GET https://scrappa.co/api/grailed/search` ## Authentication Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key. ## Parameters | Parameter | Type | Required | Description | | --- | --- | --- | --- | | `query` | string | No | Search text, e.g. undercover jacket. Optional. | | `designer` | string | No | Designer name exactly as Grailed spells it, e.g. Undercover. Comma separated for several. Use the designers endpoint for the spelling. | | `category` | string | No | Category path: a top level name such as tops, footwear or womens_tops, or a sub category such as footwear.leather. Comma separated for several. An unknown path gives a 422. | | `department` | string | No | menswear or womenswear. | | `size` | string | No | Size written as category.size, e.g. footwear.7, tops.xs or bottoms.32. Comma separated for several. An unknown size gives a 422. | | `condition` | string | No | new, gently_used, used or worn. Comma separated for several. | | `price_min` | integer | No | Lowest price in USD. For sold items it is the sold price. | | `price_max` | integer | No | Highest price in USD. For sold items it is the sold price. | | `location` | string | No | Where the item ships from: United States, Canada, United Kingdom, Europe, Asia, Australia/NZ or Other. Comma separated for several. | | `status` | string | No | for_sale (default) or sold. | | `sort` | string | No | relevance (default), newest, price_asc, price_desc, heat, heat_recency, most_liked or quality. Sold items sort by relevance, newest, price_asc or price_desc. | | `page` | integer | No | Page number, starting at 1. At most 25 (40 items per page). | ## Example response ```json { "meta": { "billable": true, "filtered_out": 0, "endpoint_family": "search" }, "items": [ { "id": 111303623, "url": "https://www.grailed.com/listings/111303623", "size": "l", "sold": false, "color": "black", "likes": 0, "price": { "amount": 685, "currency": "USD" }, "title": "Sz 3 Undercover The Shepherd Fleece Jacket", "badges": [], "market": "grailed", "seller": { "id": 319028, "rating": { "count": 481, "average": 4.9 }, "username": "MOJOs", "avatar_url": "https://media-assets.grailed.com/prd/avatar/319028/254106e53f5641188f6ae801f47caf12", "trusted_seller": true, "items_bought_and_sold": 1356 }, "styles": [], "traits": [ { "name": "color", "value": "black" }, { "name": "country_of_origin", "value": "JP" } ], "buy_now": true, "pricing": { "price_history": [], "last_drop_from": null, "original_price": null, "discount_percent": null, "price_drop_count": 0 }, "sold_at": null, "category": "outerwear", "location": "Asia", "shipping": { "au": { "amount": 60, "enabled": true }, "ca": { "amount": 60, "enabled": true }, "eu": { "amount": 60, "enabled": true }, "uk": { "amount": 60, "enabled": true }, "us": { "amount": 60, "enabled": true }, "asia": { "amount": 60, "enabled": true }, "other": { "amount": 60, "enabled": true } }, "bumped_at": "2026-11-04T14:24:07.733Z", "condition": { "key": "is_gently_used", "label": "Gently Used" }, "designers": [ { "id": 10, "name": "Undercover" } ], "created_at": "2026-11-04T14:24:13.449Z", "department": "menswear", "make_offer": true, "sold_price": null, "cover_photo": { "url": "https://media-assets.grailed.com/prd/listing/temp/206b305e552c4be39710fcf91e4bcd69", "width": 1170, "height": 1560 }, "photo_count": 9, "category_path": "outerwear.heavy_coats", "price_updated_at": "2026-11-04T14:24:13.449Z", "measurement_count": 3, "sold_shipping_price": null } ], "success": true, "pagination": { "page": 1, "has_more": true, "per_page": 40, "total_pages": 25, "total_results": 5019, "reachable_results": 1000 }, "filters_applied": { "sort": "newest", "query": "undercover jacket", "status": "for_sale", "designer": [ "Undercover" ], "price_max": 1500 } } ``` ## Errors | Status | Error | Description | | --- | --- | --- | | 422 | Validation Error | A query parameter is missing or invalid. This response is not billable. | | 422 | Unknown Category or Size | The category or size is not a Grailed value. This response is not billable. | | 503 | Upstream Unavailable | Grailed could not be reached or answered with an unexpected shape. Retry later. This response is not billable. | ## More Scrappa resources - [API documentation](https://scrappa.co/docs) - [Full LLM-readable API reference](https://scrappa.co/llms-full.txt) - [OpenAPI specification](https://scrappa.co/docs/api.json) - [Pricing](https://scrappa.co/pricing)