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.

ParameterRoutesRule
qEvery keyword search routeRequired. 1–200 characters.
qTCGplayer recent salesRequired exact numeric product ID, such as 451396.
qOfferUp listing detailsRequired OfferUp listing ID, numeric item number or item URL.
qFacebook listing detailsRequired Facebook Marketplace item ID or item URL.
qVinted listing detailsRequired Vinted item ID or item URL.
pageAll routes except TCGplayer recent sales and the listing-details routes1–100. Defaults to 1. Facebook local listings have one page, so only 1. Vinted serves 10 pages, so 1–10.
countryeBay sold and active listingsOne of us, uk, ca, au, de, fr, it or es. Defaults to us. Optional.
countryVinted active listings and listing detailsus, uk or one of 24 European countries, such as fr, de or pl. Defaults to us. Optional. Full list.
countryPoshmark sold and active listingsus or ca. Defaults to us. Optional.
countryDepop active listingsus, uk, au or ca. Defaults to us. Optional.
countryWhatnot active listingsus or ca. Defaults to us. Optional.
countryAll other routesOnly us. Optional.
marketplaceAllOptional. If sent, it must match the path: ebay, poshmark, mercari, depop, whatnot, offerup, facebook, vinted or tcgplayer.
min_priceeBay, Poshmark, Mercari, Depop, Whatnot, OfferUp, Facebook and Vinted listingsWhole units of the country's currency, 0–1,000,000. US dollars for us; another country uses its own currency. Optional.
max_priceeBay, Poshmark, Mercari, Depop, Whatnot, OfferUp, Facebook and Vinted listingsWhole 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_locationeBay sold and active listingsdomestic or worldwide. Optional. Leave it out for the eBay site's default.
buying_formateBay sold and active listingsauction, buy_it_now or best_offer. Optional.
conditioneBay sold and active listingsOne or more of new, open_box, refurbished, used or for_parts, separated by commas.
counteBay sold and active listingsRows per page: 40, 60, 120 or 200. Leave it out for 40.
category_ideBay sold and active listingseBay numeric category ID, such as 27386. Optional.
conditionPoshmark sold and active listingsExactly one of nwt, uln, ug or uf.
conditionMercari sold and active listingsExactly one of new, like_new, good, fair or poor.
conditionWhatnot active listingsExact, case-sensitive source value, such as Near Mint.
countWhatnot active listings1–24 rows; defaults to 24.
countTCGplayer product search1–24 products per page; defaults to 24. Not accepted on recent sales.
category, grading_service, gradeWhatnot active listingsSource slug and exact seller attributes, such as pokemon_cards, PSA, 10.
sortWhatnot active listingsbest_match, newest, price_asc, price_desc.
zip or lat + lonOfferUp and Facebook local listingsRequired search center: a five-digit US ZIP code, or decimal coordinates.
radiusOfferUp local listingsMiles: 5, 10, 20, 30 or 50; for cars and trucks 25, 80, 100, 200 or 5000. The applied radius is in result.location.
conditionOfferUp local listingsOne or more of new, open_box, refurbished, used, for_parts or other, separated by commas.
categoryOfferUp local listingsOfferUp category ID, such as 5.1 (Cars & Trucks).
sortOfferUp local listingsbest_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_drivetrainOfferUp car and truck searchesSee OfferUp local listings.
radiusFacebook local listingsAny whole number of miles from 1 to 100. Without it, Facebook uses about 40.
conditionFacebook local listingsOne or more of new, used_like_new, used_good or used_fair, separated by commas.
sortFacebook local listingsbest_match (default), newest, price_asc or price_desc.
deliveryFacebook local listingslocal_pickup or shipping. Optional.
days_since_listedFacebook local listings1, 7 or 30. Optional.
conditionVinted active listingsOne or more of new_with_tags, new_without_tags, very_good, good or satisfactory, separated by commas.
sortVinted active listingsbest_match (default), newest, price_asc or price_desc.
brand_id, category_idVinted active listingsVinted's numeric IDs, such as brand 53 (Nike) or category 1242 (men's trainers). Optional. Listing details return both for any listing.
conditionDepop active listingsExactly one of brand_new, used_like_new, used_excellent, used_good or used_fair.
sorteBay sold listingsbest_match (default), recently_sold, price_asc or price_desc. Price sorts include shipping.
sorteBay active listingsbest_match (default), newest, price_asc or ending_soon.
sortPoshmark active listingsbest_match (default), newest or price_asc.
sortMercari sold listingsrecently_sold (default), best_match, newest, price_asc, price_desc or most_popular.
sortMercari active listingsbest_match (default), newest, price_asc, price_desc or most_popular.
countMercari sold and active listingsMost rows per page, 1–100. Defaults to 100.
countDepop active listingsMost rows per page, 1–100. Defaults to 24.
category_id, brand_idMercari sold and active listingsMercari's numeric IDs. Optional.
cursorPoshmark, Mercari, Depop, Whatnot and OfferUpLeave 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: new is Brand New, open_box is Open Box or New (Other), refurbished is every refurbished grade, used is Pre-Owned and for_parts is Parts Only. Send several at once, like condition=new,open_box.
  • Poshmark: nwt is new with tags, uln is like new, ug is good and uf is fair. These are the same codes rows return in condition. Poshmark filters one condition at a time, so more than one returns 422. We don't send an unfiltered search instead.
  • Mercari: new, like_new, good, fair or poor, one at a time. Rows return Mercari's label, like Like New, and its numeric condition_id.
  • Depop: brand_new, used_like_new, used_excellent, used_good or used_fair, one at a time. Rows return the same codes.
  • Facebook Marketplace: new, used_like_new, used_good or used_fair. Send several at once, like condition=new,used_good.
  • Vinted: new_with_tags, new_without_tags, very_good, good or satisfactory. Send several at once, like condition=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, or min_price above max_price, returns 422 unsupported_or_invalid_query. error.param names the input to fix, like condition, cursor or zip.
  • Sending a parameter twice returns 422 duplicate_parameter.
  • On routes that take sort, sort=best_deal returns 422 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