Search inputs
Search and recent-sales parameters by marketplace: keywords, product IDs, page, price range, condition, sort, count and cursor.
Each route accepts only its documented parameters. Anything else returns 422 unsupported_or_invalid_query.
| Parameter | Routes | Rule |
|---|---|---|
q | Every keyword search route | Required. 1–200 characters. |
q | TCGplayer recent sales | Required exact numeric product ID, such as 451396. |
q | OfferUp listing details | Required OfferUp listing ID, numeric item number or item URL. |
q | Facebook listing details | Required Facebook Marketplace item ID or item URL. |
q | Vinted listing details | Required Vinted item ID or item URL. |
page | All routes except TCGplayer recent sales and the listing-details routes | 1–100. Defaults to 1. Facebook local listings have one page, so only 1. Vinted serves 10 pages, so 1–10. |
country | eBay sold and active listings | One of us, uk, ca, au, de, fr, it or es. Defaults to us. Optional. |
country | Vinted active listings and listing details | us, uk or one of 24 European countries, such as fr, de or pl. Defaults to us. Optional. Full list. |
country | Poshmark sold and active listings | us or ca. Defaults to us. Optional. |
country | Depop active listings | us, uk, au or ca. Defaults to us. Optional. |
country | Whatnot active listings | us or ca. Defaults to us. Optional. |
country | All other routes | Only us. Optional. |
marketplace | All | Optional. If sent, it must match the path: ebay, poshmark, mercari, depop, whatnot, offerup, facebook, vinted or tcgplayer. |
min_price | eBay, Poshmark, Mercari, Depop, Whatnot, OfferUp, Facebook and Vinted listings | Whole units of the country's currency, 0–1,000,000. US dollars for us; another country uses its own currency. Optional. |
max_price | eBay, Poshmark, Mercari, Depop, Whatnot, OfferUp, Facebook and Vinted listings | Whole units of the country's currency, 0–1,000,000. US dollars for us; another country uses its own currency. Optional. Must be at least min_price when you send both. |
item_location | eBay sold and active listings | domestic or worldwide. Optional. Leave it out for the eBay site's default. |
buying_format | eBay sold and active listings | auction, buy_it_now or best_offer. Optional. |
condition | eBay sold and active listings | One or more of new, open_box, refurbished, used or for_parts, separated by commas. |
count | eBay sold and active listings | Rows per page: 40, 60, 120 or 200. Leave it out for 40. |
category_id | eBay sold and active listings | eBay numeric category ID, such as 27386. Optional. |
condition | Poshmark sold and active listings | Exactly one of nwt, uln, ug or uf. |
condition | Mercari sold and active listings | Exactly one of new, like_new, good, fair or poor. |
condition | Whatnot active listings | Exact, case-sensitive source value, such as Near Mint. |
count | Whatnot active listings | 1–24 rows; defaults to 24. |
count | TCGplayer product search | 1–24 products per page; defaults to 24. Not accepted on recent sales. |
category, grading_service, grade | Whatnot active listings | Source slug and exact seller attributes, such as pokemon_cards, PSA, 10. |
sort | Whatnot active listings | best_match, newest, price_asc, price_desc. |
zip or lat + lon | OfferUp and Facebook local listings | Required search center: a five-digit US ZIP code, or decimal coordinates. |
radius | OfferUp local listings | Miles: 5, 10, 20, 30 or 50; for cars and trucks 25, 80, 100, 200 or 5000. The applied radius is in result.location. |
condition | OfferUp local listings | One or more of new, open_box, refurbished, used, for_parts or other, separated by commas. |
category | OfferUp local listings | OfferUp category ID, such as 5.1 (Cars & Trucks). |
sort | OfferUp local listings | best_match (default), newest, nearest, price_asc, price_desc; vehicle searches also newest_model, lowest_mileage. |
vehicle_make, vehicle_max_mileage, vehicle_style, vehicle_transmission, vehicle_drivetrain | OfferUp car and truck searches | See OfferUp local listings. |
radius | Facebook local listings | Any whole number of miles from 1 to 100. Without it, Facebook uses about 40. |
condition | Facebook local listings | One or more of new, used_like_new, used_good or used_fair, separated by commas. |
sort | Facebook local listings | best_match (default), newest, price_asc or price_desc. |
delivery | Facebook local listings | local_pickup or shipping. Optional. |
days_since_listed | Facebook local listings | 1, 7 or 30. Optional. |
condition | Vinted active listings | One or more of new_with_tags, new_without_tags, very_good, good or satisfactory, separated by commas. |
sort | Vinted active listings | best_match (default), newest, price_asc or price_desc. |
brand_id, category_id | Vinted active listings | Vinted's numeric IDs, such as brand 53 (Nike) or category 1242 (men's trainers). Optional. Listing details return both for any listing. |
condition | Depop active listings | Exactly one of brand_new, used_like_new, used_excellent, used_good or used_fair. |
sort | eBay sold listings | best_match (default), recently_sold, price_asc or price_desc. Price sorts include shipping. |
sort | eBay active listings | best_match (default), newest, price_asc or ending_soon. |
sort | Poshmark active listings | best_match (default), newest or price_asc. |
sort | Mercari sold listings | recently_sold (default), best_match, newest, price_asc, price_desc or most_popular. |
sort | Mercari active listings | best_match (default), newest, price_asc, price_desc or most_popular. |
count | Mercari sold and active listings | Most rows per page, 1–100. Defaults to 100. |
count | Depop active listings | Most rows per page, 1–100. Defaults to 24. |
category_id, brand_id | Mercari sold and active listings | Mercari's numeric IDs. Optional. |
cursor | Poshmark, Mercari, Depop, Whatnot and OfferUp | Leave it out on page 1. Required on later pages: send the previous result's next_cursor. |
The Playground offers observed Whatnot values for condition, category, grading service and grade. These menus are examples, not a complete Whatnot taxonomy. Choose Custom exact value to send another source value; seller-supplied grade text can vary.
#Condition uses each marketplace's own terms
condition takes the terms each marketplace uses in its own search. We don't translate conditions between marketplaces, so used on eBay has no Poshmark match.
- eBay:
newis Brand New,open_boxis Open Box or New (Other),refurbishedis every refurbished grade,usedis Pre-Owned andfor_partsis Parts Only. Send several at once, likecondition=new,open_box. - Poshmark:
nwtis new with tags,ulnis like new,ugis good andufis fair. These are the same codes rows return incondition. Poshmark filters one condition at a time, so more than one returns422. We don't send an unfiltered search instead. - Mercari:
new,like_new,good,fairorpoor, one at a time. Rows return Mercari's label, likeLike New, and its numericcondition_id. - Depop:
brand_new,used_like_new,used_excellent,used_goodorused_fair, one at a time. Rows return the same codes. - Facebook Marketplace:
new,used_like_new,used_goodorused_fair. Send several at once, likecondition=new,used_good. - Vinted:
new_with_tags,new_without_tags,very_good,goodorsatisfactory. Send several at once, likecondition=new_with_tags,very_good. Rows return the same codes.
The marketplace applies condition, min_price and max_price itself. Where present, reported_total describes matching source listings. Whatnot does not provide a reliable total. On Depop, the price filter uses Depop's search price, which can differ from the headline displayed_price.
#Other rules
- An unknown value, like
condition=mint, ormin_priceabovemax_price, returns422 unsupported_or_invalid_query.error.paramnames the input to fix, likecondition,cursororzip. - Sending a parameter twice returns
422 duplicate_parameter. - On routes that take
sort,sort=best_dealreturns422 sort_not_implemented. - A query string over 2,048 characters returns
414 uri_too_long.
There are no filters for sold date range or title patterns. Get the page, then filter the rows in your own code.
eBay sold listings · eBay active listings · Poshmark sold listings · Poshmark active listings · Mercari sold listings · Mercari active listings · Depop active listings · Whatnot active listings · OfferUp local listings · OfferUp listing details · TCGplayer product search · Facebook local listings · Facebook listing details · Vinted active listings · Vinted listing details · TCGplayer recent sales
#Repeated listings across pages
Marketplace pages are live search results, not a frozen snapshot. The same listing ID can appear on multiple pages, including with cursor pagination. Soldgraph keeps each page as the marketplace returned it, except OfferUp, where we remove listings already returned on earlier pages of the same search. Deduplicate by id when you combine pages.
See Whatnot active listings for card filters and source limitations.
Overviews: eBay sold listings API · findCompletedItems alternative · Poshmark sold listings API · Mercari sold listings API · Pokémon card price API · Sold comps API for reseller apps