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.
Run this endpoint
Endpoint
Parameters
Start with the required fields, then add optional filters only when your use case needs them.
Runnable path
This endpoint has no required query parameters.
12 optional filters available.
string
Optional
Search text, e.g. undercover jacket. Optional.
coffee shops
string
Optional
Designer name exactly as Grailed spells it, e.g. Undercover. Comma separated for several. Use the designers endpoint for the spelling.
example
string
Optional
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.
example
string
Optional
menswear or womenswear.
example
string
Optional
Size written as category.size, e.g. footwear.7, tops.xs or bottoms.32. Comma separated for several. An unknown size gives a 422.
example
string
Optional
new, gently_used, used or worn. Comma separated for several.
example
integer
Optional
Lowest price in USD. For sold items it is the sold price.
10
integer
Optional
Highest price in USD. For sold items it is the sold price.
10
string
Optional
Where the item ships from: United States, Canada, United Kingdom, Europe, Asia, Australia/NZ or Other. Comma separated for several.
Austin, Texas
string
Optional
for_sale (default) or sold.
example
string
Optional
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.
relevance
integer
Optional
Page number, starting at 1. At most 25 (40 items per page).
1
Response Schema
Example response fields are illustrative; inspect the JSON before integrating.
Example response fields
Scan these fields before integrating.
meta
items
success
pagination
filters_applied
Common items fields
id
url
size
sold
{
"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
Handle these documented responses before retrying or showing customer-facing failures.
Validation Error
A query parameter is missing or invalid. This response is not billable.
{
"errors": {
"page": [
"The page may not be greater than 25."
]
},
"message": "The request validation failed"
}Unknown Category or Size
The category or size is not a Grailed value. This response is not billable.
{
"meta": {
"billable": false,
"retryable": false,
"endpoint_family": "search"
},
"error": {
"code": "INVALID_REQUEST",
"message": "Unknown size \"footwear.99\". Use a size such as footwear.7 or tops.xs."
},
"success": false
}Upstream Unavailable
Grailed could not be reached or answered with an unexpected shape. Retry later. This response is not billable.
{
"meta": {
"billable": false,
"retryable": true,
"endpoint_family": "search"
},
"error": {
"code": "UPSTREAM_UNAVAILABLE",
"message": "Grailed is temporarily unavailable. Please retry."
},
"success": false
}Generate Code with AI
Copy a ready-made prompt with all the endpoint details, parameters, and example responses. Paste it into ChatGPT, Claude, or any AI assistant to instantly generate working code.
Try It Live
Test this endpoint in our interactive playground with real data.