Grailed APIgrailed.com ↗
Access Grailed marketplace data: search listings by designer, size, and condition; get seller profiles, reviews, categories, and curated collections.
What is the Grailed API?
The Grailed API provides 9 endpoints covering the full Grailed fashion resale marketplace — from searching listings with filters like designer, condition, and category via search_listings, to retrieving detailed seller profiles, buyer reviews, and curated homepage collections. Each listing response includes price, photos, seller info, shipping rates, and designer attribution, giving you structured access to the data that powers one of the largest menswear and womenswear resale platforms.
curl -X GET 'https://api.parse.bot/scraper/1d371b7c-7d43-4fc3-8c3e-fbce675b34ac/search_listings?page=0&sort=most_relevant&limit=40&query=nike&condition=is_new&department=menswear' \ -H 'X-API-Key: $PARSE_API_KEY'
Typed, relational, agent-ready
A generated client with real types, enums, and the links between objects — the structure a flat JSON response can't carry. Autocompletes in your editor and reads cleanly to coding agents.
- Fully typed · autocompletes
- Objects link to objects
- Typed errors & pagination
Typed Python client. Set up the SDK in your uv project, then pull this API’s typed client:
uv add parse-sdk uv run parse init uv run parse add --marketplace grailed-com-api
uv run parse add --marketplace pulls a pinned snapshot of this canonical API — it won’t change underneath you. To customize it, subscribe and swap to your own copy.
from parse_apis.grailed_api import Grailed, Sort, Condition, Department, ListingNotFound
grailed = Grailed()
# Search for Nike sneakers in menswear, sorted by newest
for listing in grailed.listings.search(query="dunks", department=Department.MENSWEAR, sort=Sort.NEWEST, limit=5):
print(listing.title, listing.price, listing.condition)
# Get full details for a specific listing
item = grailed.listings.search(query="jordan", condition=Condition.NEW, limit=1).first()
if item:
detail = grailed.listings.get(id=str(item.id))
print(detail.title, detail.price, detail.size)
# Browse similar listings from the detail instance
for similar in detail.similar(limit=3):
print(similar.title, similar.price)
# Explore a seller's listings and reviews via constructible Seller
seller = grailed.seller(id=2813854)
for review in seller.reviews(limit=3):
print(review.rating, review.note, review.tag_list)
# Typed error handling for a missing listing
try:
grailed.listings.get(id="999999999999")
except ListingNotFound as exc:
print(f"Listing not found: {exc.listing_id}")
# Discover popular designers
for designer in grailed.designers.popular(limit=10):
print(designer.name, designer.count, designer.slug)
print("Exercised: listings.search / listings.get / detail.similar / seller.reviews / designers.popular")
Full-text search over Grailed listings with optional facet filters for department, category, designer, size, and condition. Results are paginated via a page counter. Each hit includes id, title, price, designers, condition, photos, and seller info. Sort changes the underlying index.
| Param | Type | Description |
|---|---|---|
| page | integer | Page number (0-indexed). |
| size | string | Size filter (e.g. m, l, 10.5, 34). |
| sort | string | Sort order for results. |
| limit | integer | Results per page (max 100). |
| query | string | Search keyword to match against listing title and attributes. |
| category | string | Category path filter (e.g. footwear.lowtop_sneakers, tops.sweatshirts_hoodies). |
| designer | string | Designer name filter, matched exactly against the designer name field. |
| condition | string | Condition filter. |
| department | string | Department filter. |
{
"type": "object",
"fields": {
"hits": "array of listing objects with id, title, price, designers, condition, photos, seller info",
"page": "integer current page number",
"nbHits": "integer total number of matching listings",
"nbPages": "integer total number of pages"
},
"sample": {
"data": {
"hits": [
{
"id": 98387590,
"size": "m",
"user": {
"id": 3617675,
"username": "Hand_Picked_Fits",
"seller_score": {
"rating_count": 346,
"rating_average": 4.96
}
},
"price": 40,
"title": "Vintage Y2K Nike Tonal Mini Swoosh Earth Tone Hoodie",
"condition": "is_used",
"designers": [
{
"id": 30,
"name": "Nike"
}
],
"department": "menswear",
"cover_photo": {
"url": "https://media-assets.grailed.com/prd/listing/temp/90a23f9468eb48bf8ca9790f92bb88a8"
},
"category_path": "tops.sweatshirts_hoodies"
}
],
"page": 0,
"nbHits": 242198,
"nbPages": 200
},
"status": "success"
}
}About the Grailed API
Search and Listing Data
The search_listings endpoint accepts filters for query, category (using dot-notation paths like footwear.lowtop_sneakers), designer, size, condition, and sort order (most_relevant, price_low, price_high, newest, popular). Results are paginated (0-indexed page) and return an array of listing objects alongside nbHits and nbPages for cursor management. The get_listing_detail endpoint accepts a listing_id and returns the complete listing record: price, size, condition, description, photos (with url, width, height), associated designers, seller profile, and itemized shipping rates by region.
Seller and Review Data
get_seller_profile returns a seller's top_designers and an array of ratings objects. get_seller_listings pages through all active listings for a given user_id, returning the same hit shape as the search endpoint. get_seller_reviews returns the full review history for a seller including each review's rating, tag_list, free-text note, and the associated listing details — useful for building trust-signal dashboards or vetting sellers before integrating them into a workflow.
Categories, Designers, and Collections
get_categories returns the complete category hierarchy for both menswear and womenswear departments, with each node carrying a slug and subcategory paths that map directly to the category filter in search_listings. list_popular_designers returns up to 100 designer objects with id, name, slug, count (number of active listings), and departments. get_homepage_collections exposes curated capsule collections with name, published_at, followerno, and a detail_page containing slug and description.
Similarity and Discovery
The get_similar_listings endpoint takes a listing_id and returns a hits array of similar items matched by designer and category, along with pagination metadata. This is useful for building recommendation flows or scraping the competitive landscape around a specific item.
The Grailed API is a managed, monitored endpoint for grailed.com — not a raw scraper you maintain. Every endpoint is automatically health-checked on a schedule, and when grailed.com changes and a check fails, the API is automatically queued for repair and re-verified. It is built to keep working as the site underneath it changes.
This isn't an official grailed.com API — it's an independent, maintained REST wrapper over public data. Where the source has no official API (or only a limited one), Parse gives you a stable contract over a source that never promised one, and keeps it current. Need a new endpoint or field? You can revise it yourself in plain English and the agent rebuilds it against the live site in minutes — contributing the change back to the shared API is free.
Will this API break when the source site changes?+
Is this an official API from the source site?+
Can I fix or extend this API myself if I need a new endpoint or field?+
What happens if I call an endpoint that has an issue?+
- Track price trends for specific designers by querying
search_listingswithsort: price_lowandsort: price_highover time - Build a seller reputation tool by combining
get_seller_profile,get_seller_reviews, andget_seller_listingsfor a given user - Populate a resale price database by paginating
search_listingsfiltered bycondition: is_newand specific designers - Detect arbitrage opportunities by comparing
get_similar_listingsresults against a listing'spricefield - Build a category browser using the full menswear and womenswear hierarchy from
get_categories - Monitor designer popularity shifts using the
countfield fromlist_popular_designerspolled over time - Curate editorial content feeds using
get_homepage_collectionsto surface Grailed's capsule collections
| Tier | Price | Credits/month | Rate limit |
|---|---|---|---|
| Free | $0/mo | 100 | 5 req/min |
| Hobby | $30/mo | 1,000 | 20 req/min |
| Developer | $100/mo | 5,000 | 100 req/min |
One credit = one API call regardless of which marketplace API you call. Exceeding the rate limit returns a 429 response. Authenticate with the X-API-Key header.
Does Grailed have an official public developer API?+
What does `get_listing_detail` return beyond what `search_listings` provides?+
get_listing_detail returns fields not present in the search hit objects: a full description string, itemized shipping rates broken out by region, and a higher-fidelity photos array with explicit width and height per image. The search endpoint returns enough to display a card; the detail endpoint returns enough to display a full listing page.Does pagination work the same way across all list endpoints?+
page parameters and return nbHits and nbPages for range control — this applies to search_listings, get_seller_listings, and get_similar_listings. get_seller_reviews and get_seller_profile do not currently expose pagination parameters and return results in a single response. You can fork the API on Parse and revise it to add paginated review fetching if you need to handle high-volume review histories.Does the API expose sold/completed listing history or just active listings?+
search_listings or get_seller_listings. Historical sale prices and sold-out inventory are not exposed. You can fork the API on Parse and revise it to add an endpoint targeting completed transaction data if that becomes available from the source.Can I filter `search_listings` by multiple designers or sizes at once?+
designer and size parameters each accept a single value per request. Multi-value filtering is not currently supported in one call. You can parallelize requests across values client-side, or fork the API on Parse and revise it to support comma-separated or array-style multi-value inputs.