Docs menu

Grailed API endpoint

Grailed Listing Search API

Searches or browses Grailed's (grailed.com) peer-to-peer resale marketplace for currently-active listings. q, designer, department, category, size, color, condition, min_price, and max_price are all optional and combine as an AND -- a free-text q can be combined with any of the facet filters in the same request, or every field can be omitted to browse the full active catalog by Grailed's own "heat" relevance ranking. designer accepts one of the values grailed-designers' own designers[].name field returns; department, category, size, and color accept values from grailed-categories' own departments[].value/categories[].value/sizes[].value/colors[].value fields. condition and sort are fixed, closed enums (listed below). Keyword search uses typo-tolerant relevance ranking, not a guaranteed exact match. A query with genuinely zero matches returns a well-formed empty result rather than an error.

GETapiKey2 credits/requestGrailedgrailed.searchResponseDoc/grailed/search

Endpoint facts

Method: GET
API path: /grailed/search
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: Grailed
Response schema: #/definitions/grailed.searchResponseDoc

Grailed Scraper API Try Grailed Listing Search API in Playground Grailed API documentation

How this endpoint behaves

q is optional, 1 to 200 characters when present.

designer is optional, a designer/brand name filter, from grailed-designers' own designers[].name field (for example Gucci).

department is optional. Allowed values: menswear, womenswear.

category is optional, a category facet filter, from grailed-categories' own categories[].value field (for example tops, bottoms, footwear, womens_dresses).

condition is optional. Allowed values: is_new, is_gently_used, is_used, is_worn, is_not_specified.

min_price is optional, a minimum price (inclusive), in USD.

max_price is optional, a maximum price (inclusive), in USD. Must not be less than min_price when both are set.

sort is optional, defaults to heat. Allowed values: heat (Grailed's own relevance/trending ranking), heat_recency, followers (most-followed first), newest (most recently listed), price_asc, price_desc, recently_updated (most recent price update), quality (Grailed's own listing-quality ranking).

page is optional, a one-based page number, defaults to 1 (1 to 500).

limit is optional, results per page, defaults to 24, maximum 100.

Notable response behavior:

Keyword search uses typo-tolerant relevance ranking, not a guaranteed exact match.
A query with genuinely zero matches returns a well-formed empty result (count: 0, listings: []) rather than an error.
Every listing is currency USD and sold: false -- this endpoint only ever returns currently-active listings. See grailed-sold-listings for sale price history.
Each listing's id is the value grailed-listing's own id parameter expects for full listing detail.

Live monitoring

Monitored request: GET /grailed/search?q=gucci
Checks passed, 7 days to 14 Oct 2026: 100%
Median response time: 1.57 s

Current status of every endpoint

Sampled response

Request, 14 Oct 2026: GET /grailed/search?q=gucci&limit=24
Items in listings: 24
Fields filled in every checked item: 21
Fields empty in some or all items: 1

Field	Filled in, of 24 checked	Values in the sample
id	24
title	24	“Gucci wool beanie hat” and 22 other values
url	24	grailed.com
designers	24	median 1 entry
price	24	60 to 1,200, median 218
currency	24	USD in all 24
sold	24	true in 0 of 24
condition	24	is_used (10), is_gently_used (8), is_new (6)
size	24	“one size” and 9 other values
department	24	menswear (20), womenswear (4)
category	24	accessories (8), bottoms (4), outerwear (3) and 4 more
category_path	24	“accessories.hats” and 15 other values
color	24	“black” and 8 other values
location	24	Europe (8), United States (7), Asia (7) and 2 more
cover_photo_url	24	media-assets.grailed.com
photo_count	24	3 to 22, median 9
follower_count	23	2 to 12, median 5
buy_now	24	true in 24 of 24
make_offer	24	true in 24 of 24
created_at	24	2026-10-11 to 2026-10-13
bumped_at	24	2026-10-11 to 2026-10-13
seller	24

Request parameters

Parameter	Type	Required	Default	Description	Example
q	string	No		Free-text search query	gucci
designer	string	No		Designer/brand name filter, from grailed-designers' own designers[].name field	Gucci
department	string	No		Department filter Allowed values: menswear, womenswear.	menswear
category	string	No		Category facet filter, from grailed-categories' own categories[].value field	tops
size	string	No		Size facet filter, from grailed-categories' own sizes[].value field	m
color	string	No		Color facet filter, from grailed-categories' own colors[].value field	black
condition	string	No		Condition filter Allowed values: is_new, is_gently_used, is_used, is_worn, is_not_specified.	is_gently_used
min_price	number	No		Minimum price (inclusive), in USD	50
max_price	number	No		Maximum price (inclusive), in USD	500
sort	string	No	heat	Sort order, defaults to heat Allowed values: heat, heat_recency, followers, newest, price_asc, price_desc, recently_updated, quality.	heat
page	integer	No	1	One-based page number, defaults to 1	1
limit	integer	No	24	Results per page, defaults to 24, maximum 100	24
x-api-key (header)	string	Yes		API key required

cURL example

curl -X GET "https://api.crawlora.net/api/v1/grailed/search?q=coffee&department=menswear&condition=is_new&sort=heat&page=1&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Example JSON response

{
  "code": 200,
  "msg": "OK",
  "data": {
    "query": "gucci",
    "sort": "heat",
    "page": 1,
    "limit": 24,
    "count": 1,
    "total_results": 250601,
    "total_pages": 10442,
    "listings": [
      {
        "id": 105379689,
        "title": "Chateau Marmont Gucci Tshirt Red Japan Exclusive",
        "url": "https://www.grailed.com/listings/105379689",
        "designers": [
          "Gucci"
        ],
        "price": 400,
        "currency": "USD",
        "sold": false,
        "condition": "is_gently_used",
        "size": "m",
        "department": "menswear",
        "category": "tops",
        "category_path": "tops.short_sleeve_shirts",
        "color": "black",
        "location": "United States",
        "cover_photo_url": "https://media-assets.grailed.com/prd/listing/temp/dc6e1242b28a48bba80b5a353bb8c869",
        "photo_count": 7,
        "follower_count": 712,
        "buy_now": true,
        "make_offer": true,
        "seller": {
          "id": 10332947,
          "username": "woodlandstepps",
          "total_bought_and_sold": 52,
          "trusted_seller": false,
          "rating_average": 4.78,
          "rating_count": 9
        }
      }
    ]
  }
}

Request schema

No body schema

Response schema

#/definitions/grailed.searchResponseDoc

Field	Type	Required	Example
code	integer	No	200
data	grailed.SearchResponse	No
data.category	string	No
data.color	string	No
data.condition	string	No
data.count	integer	No
data.department	string	No
data.designer	string	No
data.fetched_at	string	No
data.limit	integer	No
data.listings	array	No
data.listings[].bumped_at	string	No
data.listings[].buy_now	boolean	No
data.listings[].category	string	No
data.listings[].category_path	string	No
data.listings[].color	string	No
data.listings[].condition	string	No
data.listings[].cover_photo_url	string	No
data.listings[].created_at	string	No
data.listings[].currency	string	No
data.listings[].department	string	No
data.listings[].designers	array	No
data.listings[].follower_count	integer	No
data.listings[].id	integer	No
data.listings[].location	string	No
data.listings[].make_offer	boolean	No
data.listings[].photo_count	integer	No
data.listings[].price	number	No
data.listings[].seller	grailed.ListingSeller	No
data.listings[].seller.avatar_url	string	No
data.listings[].seller.id	integer	No
data.listings[].seller.rating_average	number	No
data.listings[].seller.rating_count	integer	No
data.listings[].seller.total_bought_and_sold	integer	No
data.listings[].seller.trusted_seller	boolean	No
data.listings[].seller.username	string	No
data.listings[].size	string	No
data.listings[].sold	boolean	No
data.listings[].sold_at	string	No
data.listings[].sold_price	number	No
data.listings[].title	string	No
data.listings[].url	string	No
data.max_price	number	No
data.min_price	number	No
data.page	integer	No
data.query	string	No
data.size	string	No
data.sort	string	No
data.source_url	string	No
data.total_pages	integer	No
data.total_results	integer	No
msg	string	No	OK

Failure responses

Status	Description	Schema
400	Bad Request	#/definitions/app.Response
429	Too Many Requests	#/definitions/app.Response
503	Service Unavailable	#/definitions/app.Response

Code examples

Use environment variables for secrets and keep Crawlora API keys server-side.

curl -X GET "https://api.crawlora.net/api/v1/grailed/search?q=coffee&department=menswear&condition=is_new&sort=heat&page=1&limit=10" \
  -H "x-api-key: $CRAWLORA_API_KEY"

Shared guides

Authentication Errors and retries Rate limits and credits Pricing Acceptable use

More Grailed endpoint docs Grailed Scraper API List Grailed's facet taxonomy API documentation Grailed Collection Listings API documentation Grailed Collections API documentation Grailed Designer Directory API documentation Get a Grailed listing API documentation Grailed Seller Reviews API documentation

Open in Playground Back to group

Docs menu

Grailed API endpoint

Grailed Listing Search API

GETapiKey2 credits/requestGrailedgrailed.searchResponseDoc/grailed/search

Endpoint facts

Method: GET
API path: /grailed/search
Auth: apiKey
Credits: 2 credits/request
Charged on: Successful 2xx responses only
Platform: Grailed
Response schema: #/definitions/grailed.searchResponseDoc