Marketplace sources: StockX, Poshmark, Mercari and 9 more
The same key that reads eBay reads 12 more marketplaces, plus PSA's auction price record as its own source. Add source= to /v1/sold, /v1/comps or /v1/active to pick a marketplace, or source=all to merge the 12 marketplaces into one newest first answer with each sale tagged by where it sold. The eBay endpoints and their parameters are documented in the main API reference; this section covers everything that changes when source is set.
Looking for what each marketplace covers and what it costs? See all marketplaces and pricing. This page is the technical reference.
GET https://api.compsapi.com/v1/sold?source=reverb&q=fender+stratocaster&stats=1
GET https://api.compsapi.com/v1/comps?source=all&q=michael+jordan
GET https://api.compsapi.com/v1/active?source=poshmark&q=lululemon+align
Every plan, Free included, reads every source. One call is one request from the same monthly quota as your eBay calls, and source=all is still one request.
Coverage at a glance
Each source has its own reference page with its fields, condition labels and limits.
| Source | Category | Sold history from | Authenticity basis | In the row |
|---|---|---|---|---|
| reverb | Music gear | 2014 | seller_declared | Brand, model, finish, category, seller country, list price, discount, days on market |
| stockx | Sneakers, streetwear | 2019 | marketplace_verified | Size, order type, order book as recorded with the sale, premium over retail, sell through |
| goat | Sneakers, apparel | August 2026, growing | marketplace_verified | US size, new, used or new with defects, style code |
| grailed | Designer menswear | 2017 | seller_declared | List price, price drops, days on market, seller rating and sold count |
| poshmark | Clothing, accessories | November 2025 | seller_declared | Original list price, discount, days on market, brand, size |
| mercari | Broad resale (US) | November 2025, growing | seller_declared | Paid price, list price, days on market, seller verification and rating |
| vinted | Clothing (US by default, other markets with market=) | October 2026, growing | seller_declared | Sold price, brand, size, condition, days to sell |
| goldin | Card and memorabilia auctions, Goldin Marketplace | November 2012 | graded, or seller_declared on ungraded lots | Grade, bids, opening bid, reserve, buyer's premium, Goldin Marketplace list price and accepted offers |
| fanatics | Card auctions and buy now | 2008 | graded with certificate number | Grade, certificate number, guide value, auction detail, hammer and buyer paid price, front and back images on most recent sales |
| myslabs | Graded cards | 2020 | graded, or seller_declared when no grade is stated | Grade, grader, views, watchers |
| pristine | Autograph and memorabilia auctions | April 2010 | third_party_coa | Certifier, bids, opening bid, hammer price and price with buyer's premium, images |
| tcgplayer | Trading card game singles | Individual sales for about the last 120 days, weekly summaries back to April 2023 | seller_declared | Condition, variant, card number, rarity, set code |
| psa | PSA auction prices realized | Cards held today, mostly 2025 onward | graded with PSA certificate number | PSA spec id, grade, certificate number, venue |
psa is PSA's record of sales made on other venues, so it is its own source and source=all does not merge it. source=all merges the 12 marketplaces above it in the table. eBay stays on its own calls (leave source off, or pass source=ebay).
Card tools
PSA cert lookup, population and card lookup: /v1/cert turns a PSA cert number into the card, its grade, the population at that grade and higher, and recent sales. /v1/lookup resolves a card keyword to its PSA spec id, and /v1/population returns PSA's count at every grade with the gem rate, for one card or a whole set. The same spec id is on every source=psa sold row.
What every source shares
- One schema. A marketplace row has the same core fields as an eBay row, so one parser reads every source. Marketplace rows add
source,authenticity,flags, and where the marketplace has themsignals,marketandraw. - One authenticity object on every row.
authenticity.basissays how an item's standing is known: checked in hand by the marketplace, graded with or without a certificate number, certified by a third party, or the seller's word. It is passed through from the marketplace and never our judgment. - One merged call.
source=allreturns sales from 12 marketplaces, newest first, each tagged with itssource. A slow marketplace never fails the call. - Cleaned stats.
statsgives median, mean, quartiles and range after junk and outliers are left out, with a confidence score, a price trend and a median per condition. - An AI junk filter you switch on.
exclude=ai_junkdrops lots, parts, accessories, empty boxes and replicas from the rows and the stats using labels from our AI model, andai=1shows the label on every row. - Live listings.
/v1/active?source=returns what is for sale right now on all 12 marketplaces, with deep paging on Poshmark, Mercari, Vinted and Reverb. - Markets.
market=narrows sold answers to one country or region on the sources that sell in more than one currency.
The sections below are the common reference for all of this.
Endpoints
| Endpoint | What it returns |
|---|---|
GET /v1/sold | Sold listings for a search, newest sale first, paginated. stats=1 adds aggregates. |
GET /v1/comps | Price stats over every matching sale in the window plus the 10 newest matching sales. The title rules filter is on by default (exclude=junk). Not pageable. |
GET /v1/active | Listings for sale right now on the marketplace. See live listings. |
GET /v1/sources | The valid source names, which ones source=all merges and which have live listings. No key needed, not counted. |
GET /v1/cert, GET /v1/lookup, GET /v1/population | PSA cert lookup, card lookup and population census for a card or a whole set. See card tools. |
Base URL, key and headers are the same as for eBay: https://api.compsapi.com, with your key in X-API-Key or Authorization: Bearer.
Choosing a source
source takes one name or all. A comma list is not accepted:
GET /v1/sold?source=reverb&q=fender+stratocaster
GET /v1/sold?source=all&q=michael+jordan&stats=1
The names are reverb, stockx, goat, grailed, poshmark, mercari, vinted, goldin, fanatics, myslabs, pristine, tcgplayer and psa. Leaving source off, or passing source=ebay, is the eBay API described in the main reference. An unknown name returns 400 with the list of valid ones.
source=all merges the 12 marketplaces into one answer sorted by sale time, newest first. Every row carries its own source, and meta reports what happened for each marketplace on that request. It does not include eBay rows, and it does not include psa: PSA's record is made of sales that happened on other venues (mostly eBay, Fanatics Collect and Goldin), so merging it would count the same sale twice. Ask for source=psa by name.
Prices in a merged answer are all USD, but marketplaces differ in what the price includes (hammer price, buyer paid total, price with premium). Auction sources state theirs in raw.price_basis.
Parameters
These apply to /v1/sold and /v1/comps on every marketplace source.
| Parameter | Default | Meaning |
|---|---|---|
source | ebay | One marketplace name, or all. |
q | required | Search words, max 300 characters. Every word must appear in the title. |
days | 90 | How far back to search, in days from today. On marketplace sources days runs from 1 to 7000 and the window never starts earlier than 2008-01-01. eBay stays at 1095. The days in the answer is the length actually served. |
start, end | off | A fixed window written YYYY-MM-DD, in place of days. start alone runs to today, end alone covers the days before it, and end never runs past today. The answer carries window with the period served. |
page, size | 1, 200 | Pagination on /v1/sold. size is 10 to 240, and a value outside that range is moved to the nearest limit. next_page says whether another page exists. /v1/comps has no size. |
stats | off | stats=1 adds the stats block on /v1/sold. Always on for /v1/comps. Only 1 switches stats, ai and native_price on. |
min_price, max_price | off | Keep only sales inside a price range, in USD. A sale with no price is dropped when min_price is set. |
condition | off | Keep only sales whose condition equals this word, ignoring case and treating spaces and underscores alike. See condition. Comma separate to combine. |
exclude | off on /v1/sold, junk on /v1/comps | junk drops rows with a title flag, and one flag name or a list (exclude=lot,sealed) drops only those. ai_junk drops every row our AI model reads as not a single normal item, and parts, box_only, digital or accessory drop one kind, see AI junk filter. none keeps everything. Combine as exclude=junk,ai_junk. A word that is not on this list drops nothing. |
ai | off | ai=1 adds the ai label object to every returned row. See AI junk filter. |
native_price | off | native_price=1 fills native_price and native_currency on every row, including sales that were already in USD. |
market | us on Vinted, off elsewhere | Keep only sales made in one market, read from the currency the sale was made in: us, uk (or gb), eu, pl, cz, hu, ro, se, dk, ca, au, or all. A comma list combines markets (market=uk,eu). A code that is not on this list is ignored and filters nothing, so on Vinted it returns every market. See markets. |
include | off | include=summaries on /v1/sold adds TCGplayer's weekly summary rows. See the TCGplayer page. /v1/comps is individual sales only. |
product_id, style_id, item_size, kids | off | source=stockx and source=goat only: one product, one style code, one size, and whether kids' versions are included. See the StockX page. On another source product_id, style_id and item_size return 400, and kids has no effect. |
Markets
market= applies to /v1/sold and /v1/comps on every marketplace source. It keeps the sales made in that market's currency: us is USD, uk is GBP, eu is EUR, and each country code is that country's currency. price stays in USD on every row, with the original amount in native_price and native_currency.
source=vinted answers United States sales when market is not sent, on its own and inside source=all. Pass market=all for every Vinted market, or name the ones you want. Every other source returns all its sales unless you pass market. StockX and GOAT sales are all in USD, so a market other than us returns nothing there. eBay keeps its own site parameter.
Parameters that are eBay only
These belong to the eBay API and have no effect when source is a marketplace: best_offer, cards, grader, grade, graded, lang, card_condition, first_edition, require, print_run, site and category. They have no effect and give no error: the 200 answer lists them under ignored_params, along with any parameter name the service does not know. So a call such as source=fanatics&grader=PSA&grade=10 returns every Fanatics match. To narrow a marketplace search, put the words in q (q=michael+jordan+psa+10) or filter with condition.
Condition is each marketplace's own label
On eBay, condition takes five fixed buckets. On a marketplace source it is an exact match, ignoring case and treating spaces and underscores alike, against one plain set of words per marketplace, and the same words are used on sold rows and on live listings. Poshmark: new_with_tags, like_new, good, fair. Grailed: new, gently_used, used, worn. Vinted: new_with_tags, new_without_tags, very_good, good, fair. Mercari: new, like_new, good, fair, poor. Reverb: Brand New, Mint, Excellent, Very Good, Good, Fair, Poor, B-Stock, Non Functioning. StockX: new. GOAT: new, new_with_defects or used. TCGplayer: Near Mint, Lightly Played, Moderately Played, Heavily Played, Damaged. Fanatics Collect gives the slab label, such as PSA 10, or the grader alone (PSA) when no grade is stated. MySlabs rows are graded for a slab, ungraded for a raw card or comic, sealed for wax, or null when the listing does not say. Goldin, Pristine Auction and PSA rows have no condition. A seller who states no condition leaves it null. To see the labels for your own search, read stats.by_condition, which groups the matched sales by label. With source=all, a condition value only matches the marketplaces that use that word.
Response
/v1/sold returns ok, query, page, ms, count (rows on this page), no_results, next_page, days, size, source, window (start and end), items, stats when asked for, and meta. meta can carry diagnostic keys beyond the ones listed on this page. Do not build on them. cached is false and cached_age_s is 0 on marketplace sold answers.
/v1/comps returns ok, query, ms, source, count (matching sales after filters), count_before_filters (keyword matches read in the window before condition, price and exclude ran; on a very broad search it is the number read, a lower bound and not a total), no_results, window, stats, items (the 10 newest) and meta.
Fields on every sold row
| Field | Meaning |
|---|---|
item_id | A stable id for the sale, unique within its source. Its format differs by marketplace, and the marketplace's own listing or product ids are in raw. |
title | The listing title as it sold. |
last_sold | When it sold, UTC, as YYYY-MM-DDTHH:MM:SSZ. |
price | Sale price in USD. A sale in another currency is converted at the European Central Bank rate for the sale date. null when no rate exists for that currency and day. |
native_price, native_currency | The original amount and currency of a sale that was not in USD. Filled on every row with native_price=1. |
units_sold, total_sales | Quantity and total. A marketplace row is one sale, so these are 1 and the price, except TCGplayer weekly summary rows, which you only get with include=summaries (see the TCGplayer page). |
format | FIXED_PRICE or AUCTION. Goldin and Pristine Auction lots and Fanatics Collect weekly and premier auction lots are AUCTION. Fanatics Collect buy now sales are FIXED_PRICE. |
bids | The number of bids on an auction lot (Goldin, Pristine Auction, Fanatics Collect auctions), else null. PSA records carry no bid count. |
condition | The marketplace's own condition label, or null. |
shipping_cost | Shipping in USD when the marketplace gives it. |
url, image | Link to the sale and its photo when available. |
us_sale | An eBay field. Always null on marketplace rows. |
source | Which marketplace this sale is from. Always present. |
authenticity | How the item's standing is known. See authenticity. |
flags | Data quality flags from title rules. Always present, empty when nothing matched. See flags. |
brand, category, size | Reverb, Mercari and Poshmark sold rows: the item's brand, category path (Electronics / Video games & consoles / Consoles) and size, as names. Present when the marketplace gives them. |
listing_id, seller_country | Reverb sold rows, keyword and ids= alike: the Reverb listing id (item_id stays the sale record id), and the seller's country as a two letter code when known. |
row_type | Only on TCGplayer weekly summary rows: weekly_summary. |
attributes | On goldin, fanatics and pristine: year, is_rookie, is_autographed, is_memorabilia, serial_number, serial_limit, one_of_one and basis. See the source pages. |
price_is_estimate | Present and true only on a Fanatics Collect Premier lot whose settled price is not in yet: price is then the hammer price plus the 20% buyer's premium. |
card | Card details (graded, grader, grade, grade_label, card_number, year, language, first_edition, flags, and on Fanatics Collect is_rookie, is_autographed, is_memorabilia, serial_number, serial_limit) where the row looks like a card. On source=psa it also holds psa_spec_id. Read grade and grader from authenticity, which is filled on every source. |
signals | Days on market, discount, listing date and seller standing under the same names on every marketplace. Present when the marketplace has any of them. See signals. |
market | StockX only: the order book and price dynamics recorded with the sale. See the StockX page. |
ai | Only with ai=1: the AI model's label for the row. See AI junk filter. |
raw | Everything else the marketplace gives, under that marketplace's own key names. Each source page lists what is there. raw can carry keys not listed on the source page. Listed keys are stable. |
Authenticity
Every sold row carries one authenticity object with the same shape on every source:
"authenticity": { "basis": "graded", "verified": true, "grader": "PSA", "grade": "10", "cert_number": "82979511" }
basis is one of:
marketplace_verified: the marketplace checked the item in hand before the sale (StockX, GOAT).gradernames the marketplace.graded: a grading company graded it.graderandgradeare filled, andcert_numberwhen the marketplace gives it (Fanatics Collect, PSA).third_party_coa: a third party issued a certificate of authenticity, such as Beckett or JSA (Pristine).gradernames the certifier.seller_declared: only the seller's description stands behind the item. This is the value for clothing, gear and ungraded items.
verified is true only for a marketplace in hand check or a certificate number the marketplace itself confirms (Fanatics Collect, PSA). A grade without a confirmed certificate number reads graded with verified: false. Pristine rows add coa_note with the certifier's wording. The object is passed through from the marketplace. We do not assess whether an item is genuine.
Signals
signals puts the common per sale signals under one set of names, so you read them the same way on every source:
"signals": {
"days_on_market": 18.8,
"discount_pct": 14.1,
"listed_date": "2026-10-29T19:08:13Z",
"seller": { "username": "example_seller", "rating": 4.99, "rating_count": 132, "items_sold": 303, "verified": true }
}
| Field | Meaning |
|---|---|
days_on_market | Days from listing to sale. |
discount_pct | Percent under the list price it sold for. |
listed_date | When it was listed, UTC. |
seller | username, rating, rating_count, items_sold and verified (identity checked or trusted seller standing), each present only where the marketplace gives it. |
The values come from the marketplace's own dates and prices. A value the marketplace does not have is left out, and the whole object is absent on sources with none of them: StockX, GOAT and TCGplayer. MySlabs and Vinted listing dates are estimates, and their pages say so.
Flags
Every row carries a flags array from rules that read the title. It is empty when nothing matched.
| Flag | Means |
|---|---|
lot | Several items sold together (lot, bundle, bulk). |
mystery | Mystery, random or repack listing. |
sealed | Sealed product. |
accessory | Sleeve, toploader, case, binder or stand. |
replica | Title says replica, reprint, proxy, custom or novelty. |
not_graded_claim | Title describes a grade in words ("gem mint", "would grade"). |
keyword_stuffing | A very long title padded with separators. |
title_missing | No usable title. |
outlier | The price is a statistical outlier for the matched set. Added only when stats runs. |
exclude=junk drops rows with any flag except outlier, and it is the default on /v1/comps. exclude=none keeps everything.
The rules read words in the title. The card rules apply to card sources and to card titles, so a graded slab titled "PSA 10 GEM MINT" or a Fender Custom Shop guitar is not flagged. Words cannot tell an instrument from a part that names it, so on gear and clothing the rules miss most parts and accessories: use the AI junk filter below for those. Parts, empty boxes and digital items are not flags: read them in ai.kind with ai=1.
On Reverb, Mercari, Poshmark and Vinted a second check covers this. When the sales for a search fall into two separate price groups and the cheaper group is mostly parts or accessories (by the marketplace's own category, or by words such as case, knob, charger or "for parts" that the search did not ask for), those rows get the accessory flag. Rows in a parts or accessories category that sell for well under the rest are flagged the same way. The check needs the whole set of matching sales, so it runs on /v1/comps and on /v1/sold with stats=1. A search that asks for a part or an accessory itself ("juno-106 slider", "switch oled case") is never filtered, and exclude=none switches the check off.
AI junk filter
Our AI model reads each sale's title and price and labels what was sold: the item itself, or a lot, a mystery box, a part, an accessory, an empty box, a replica or a digital item. It is opt in on every plan, and it works on every marketplace source. The same two parameters, exclude=ai_junk and ai=1, work on eBay calls: see the eBay reference. A plain call returns every sale.
| Parameter | Effect |
|---|---|
exclude=ai_junk | Removes the rows the model labels as junk, from items and from the stats: anything that is not a single normal item, plus raw cards sold as grading candidates. |
exclude=parts, box_only, digital | Removes only the rows the model labels with that kind. The other kinds stay in the rows and the stats. |
exclude=accessory | Removes rows with the accessory flag (title rules, and the parts and accessories check on Reverb, Mercari, Poshmark and Vinted) and rows the model labels accessory. |
ai=1 | Adds the ai object to every returned row, filtered or not. Nothing is removed, and flags and the stats do not change. |
exclude is one list, so combine the two filters as exclude=junk,ai_junk. On /v1/comps, passing exclude replaces the default junk, so pass both names to keep the title rules as well (exclude=junk,parts for the title rules plus one kind).
GET /v1/sold?source=reverb&q=fender+stratocaster&days=30&stats=1
GET /v1/sold?source=reverb&q=fender+stratocaster&days=30&stats=1&exclude=ai_junk&ai=1
On 18 November 2026 the first call read a median of about $400 and the second about $900, with about 1,130 of about 2,830 sales removed.
"ai": { "kind": "item", "junk": false, "confidence": 0.987, "category": "music_gear", "model": "2026-11-17" }
ai field | Meaning |
|---|---|
kind | What was sold: item, lot, mystery, parts, accessory, box_only, replica, digital or other. |
junk | true when kind is not item, or when the row is a raw card sold as a grading candidate. This is what exclude=ai_junk filters on. |
confidence | 0 to 1: how sure the model is of the item or not item call. |
category | A broad product category for the row, for example music_gear. |
model | The release date of the model that made the call, for example 2026-11-17. |
When either parameter is used, meta.ai reports status (ok, or why labels were not available), rows (rows looked at), unlabelled, dropped (rows removed by exclude=ai_junk) and ms. Nothing is ever deleted: a row without a label is kept, and if labels are unavailable the call still succeeds with every row in place. A very recent sale can come back before it has a label. It is kept, and unlabelled counts such rows.
In testing the model made the same junk or not junk call as our test labels on 97.7% of 600 marketplace listings and on about 92% of listings on eBay searches it had never seen. Each of the 996 test listings was labelled twice independently, the handful of disagreements were settled by review, and none of these listings were used to train the filter. These figures measure how well the filter sorts junk from real items. They are not a measure of the sold data, which comes back exactly as recorded with or without the filter. The junk filter page has the figures by marketplace. The effect is largest on gear and broad resale keywords. A specific clothing style or a signed item often moves very little. A pickup set or a pedal sold as a product in its own right counts as an item.
Stats
stats is computed over priced sales after two steps: rows carrying a title flag are left out (pass exclude=none to keep them in), then prices more than 1.5 times the interquartile range outside the middle half are left out as outliers (4 or more sales needed).
It reads at most the newest 20,000 matches. With source=all that limit is across all marketplaces together, so on a broad keyword the stats can cover only the most recent days. oldest_sale shows how far back they reach. Narrow the keyword or the window when it matters.
| Field | Meaning |
|---|---|
count | Priced sales matched. |
used_for_stats | Sales the figures were computed from. |
median, mean, p25, p75, min, max | USD, over used_for_stats. |
junk_removed, outliers_removed | How many rows each step left out of the stats. |
newest_sale, oldest_sale | The time span covered, UTC. |
confidence | score, label, n and relative_iqr. See below. |
price_trend | direction, pct_change, recent_median, prior_median and n. See below. |
by_condition | The 12 most common condition labels, each with count and median. Sales with no condition label are grouped under unknown. null when only one label exists. |
accessories_removed | How many matched sales the parts and accessories check flagged. 0 on sources it does not run on. |
days_to_sell | median, p25, p75, min, max and n: days from listing to sale over the sales that carry a checked value. n is that dated subset, not every row. null when there are too few. Filled on Vinted today. |
sold_within_days | A list of within_days (1, 3, 7, 14, 30) and sold_pct: the share of those dated sales that sold within that many days. It describes items that sold. It is not a sell through rate, because unsold listings are not counted. Needs 8 or more dated sales. |
products, by_product | StockX and GOAT: how many products are inside the headline figures, and up to 12 matched products with their own count, median, p25, p75, min, max, newest_sale, kids and in_stats. See the StockX page. |
On /v1/sold?stats=1, flagged rows stay in items and junk_removed counts them. On /v1/comps the default exclude=junk removes them before stats run, and the number removed is count_before_filters minus count. stats.accessories_removed is how many of those were parts or accessories of the searched product, and meta.accessory_filter reports the check: flagged, basis (price_cluster, category or both), the split_price between the two price groups with low_median and high_median, and on Mercari the main_category of the search. Rows removed by exclude=ai_junk are counted in meta.ai.dropped.
Example, GET /v1/comps?source=reverb&q=roland+juno-106 (90 days, 21 November 2026): 107 keyword matches, 43 flagged as parts, median $1,650 over the synths. With exclude=none the same search reads $240.
Stats count individual sales only. TCGplayer weekly summary rows are never counted, with or without include=summaries.
confidence is a plain score for how far to trust the median. score is min(1, n / 30) multiplied by 1 - relative_iqr, where n is used_for_stats and relative_iqr is the interquartile range divided by the median. label is high from 0.66, medium from 0.33, else low. A broad keyword with a wide price spread reads low even with thousands of sales, because the sales are not one product. Narrow the keyword or filter by condition to raise it.
price_trend sorts the sales used by date, splits them into an older half and a recent half by count, and compares the two medians. direction is up or down when the change is more than 2%, else flat. It needs 8 or more dated sales and is null below that. The halves hold equal numbers of sales, so they can cover different lengths of time, and a change in what is selling moves the figure as well as a change in price. It is not meaningful on Vinted, where sale dates are approximate.
The meta block
A marketplace answer holds the sales history for your search and, on most sources, the sales made since it was last updated. meta reports on that, per marketplace:
| Key | Meaning |
|---|---|
meta.topup.<source>.status | ok, skipped, timeout or error. With skipped, reason is one of window_closed (the window ends in the past), no_query, fresh (nothing newer to add), no_match (the keyword matched no product, on TCGplayer and StockX), busy (try again) or not_supported. |
meta.topup.<source>.new | Newer sales added to this answer. |
meta.gapfill.<source>.status | covered (the window was already held), ok (older sales were added on this call), pending (more are being added, call again), skipped or error (nothing was added, and the rows held are returned). complete is true when the whole window is held. |
meta.ai | AI filter report, when ai=1 or exclude=ai_junk is used. |
meta.accessory_filter | The parts and accessories check, when it flagged rows. See stats. |
meta.scope | StockX and GOAT: the product scope applied (product_id, style_id, item_size, kids), with kids_rows_excluded, kids_products_excluded and a hint when kids' versions were left out. |
meta.summaries | TCGplayer: excluded is the number of weekly summary rows left out of this answer, and include names the value that returns them. |
A marketplace call can take a second or two, and a merged source=all call with stats longer. If one marketplace is slow or unavailable, the answer still returns with the sales held for it, and its meta entry says what happened.
Live listings
GET /v1/active?source=<marketplace>&q= returns what is listed for sale on that marketplace at the moment you ask, on all 12 marketplaces. One call is one request. Sold and live are separate searches: to set what is listed against what sold, call both.
GET /v1/active?source=poshmark&q=lululemon+align
GET /v1/active?source=all&q=jordan+1+chicago
| Parameter | Default | Meaning |
|---|---|---|
q | required | Search words, max 300 characters. Each marketplace ranks live results its own way, so a listing can lack one of your words. Sold calls require every word. |
sort | best_match | best_match, newly_listed, price_asc, price_desc or ending_soonest. Each source page lists its sorts. A sort a marketplace does not have is accepted and falls back to its own order. An unknown value is served as best_match, and sort comes back in ignored_params. |
per_page, page | one search page, 1 | Results per page (10 to 240) and page number. On Poshmark, Mercari, Vinted and Reverb the default page is 48 to 60 listings, a page can be any size up to 240 and page=2, page=3 and so on return the next listings. A deep page can come back short (past about 500 listings on Poshmark and 600 on Mercari), so use cursor to go further. On the other marketplaces one call returns one search page, usually 20 to 70 listings. |
cursor | none | Poshmark, Mercari, Vinted and Reverb only. Pass the next_cursor of the previous answer to get the listings that follow it. Send the same q, source, sort and filters as the call that returned it. A cursor from another search is refused with a 400. |
product_id, style_id, item_size, kids | off | source=stockx and source=goat only. See the StockX page. |
min_price, max_price | off | Price range in USD. |
condition | any | Exact match on the marketplace's condition word, the same words as on sold calls. |
format | both | bin for fixed price listings only, auction for auctions only. |
On Poshmark, Mercari, Vinted and Reverb min_price and max_price are applied by the marketplace's own search, so max_price=40 returns listings under $40 from the whole marketplace and paging walks through all of them. condition and format are applied to the listings read for the answer, so a page can come back shorter than per_page: keep following next_cursor until it is null. On the other marketplaces all four filters are applied to the one search page read, and a filter that leaves count: 0 means none of those listings matched, not that the marketplace has none.
Paging deep
One call returns up to 240 listings. To read further, pass next_cursor back as cursor:
GET /v1/active?source=vinted&q=levis+501&max_price=40&per_page=240
GET /v1/active?source=vinted&q=levis+501&max_price=40&per_page=240&cursor=<next_cursor>
next_page is true and next_cursor is set while the marketplace has more. marketplace_total is the marketplace's own count for the search, as it reports it (Poshmark stops counting at 5,000 and Mercari at 10,000). How far a search goes is set by the marketplace:
| Marketplace | Default page | Reach of one search |
|---|---|---|
| Poshmark | 48 | Thousands of listings. |
| Mercari | 60 | best_match returns Mercari's top 300 to 430 matches. newly_listed, price_asc and price_desc go on through every match. |
| Vinted | 48 | 960 listings, Vinted's own limit per search. Narrow with min_price and max_price to reach more. |
| Reverb | 50 | Every match. Under best_match Reverb re-ranks between pages, so a listing can appear twice across calls and another can be missed. Use newly_listed, price_asc or price_desc for a complete pass with no repeats. |
Listings are live, so a listing can sell or a new one can appear between two calls. source=all returns one page per marketplace and has no cursor: page one marketplace at a time for depth.
| Field | Meaning |
|---|---|
item_id, title, url, image | The listing. Live item_id values are prefixed with the source name (poshmark-...). Strip the prefix to compare with a sold row. |
price, currency, price_max | The asking price now. On an auction this is the current bid. price_max is the top of a price range, else null. |
shipping, shipping_text | Shipping cost when the marketplace shows it. |
format | BIN or AUCTION. |
bids, ends_at | Auctions: bids so far and the closing time, UTC. |
buy_it_now_available, best_offer_enabled, quantity_available | Buying options where the marketplace has them. |
condition, seller, seller_feedback, seller_positive_pct, location | As the marketplace states them. Fields a marketplace does not have are null. |
source | Which marketplace the listing is on. |
authenticity | The same object as on sold rows, when the marketplace gives a standing. |
raw | Marketplace specific extras, listed on each source page. |
The response carries ok, query, page, ms, sort, count, next_page, source, total_active, total_active_is_minimum, cached, cached_age_s, live_status, sources_failed and items. live_status is an object keyed by marketplace, with one plain word for each one asked: ok, ok_cached (answered from the 60 second cache), no_match (the keyword matched no product, on TCGplayer), busy (retry), timeout, error or not_available. sources_failed is a sorted list of the marketplaces that answered timeout, error or busy, and is [] when all answered. On Poshmark, Mercari, Vinted and Reverb the response also carries per_page, next_cursor (null at the end) and marketplace_total when the marketplace gives a count. source=tcgplayer adds price_points, see the TCGplayer page.
{
"ok": true,
"live_status": { "goat": "error", "pristine": "timeout", "vinted": "busy", "tcgplayer": "no_match", "reverb": "ok", "stockx": "ok_cached" },
"sources_failed": ["goat", "pristine", "vinted"]
}
A call still answers 200 when a marketplace fails. A marketplace named in sources_failed was not reached, which is different from having no listings: retry it, and do not read a zero count as nothing for sale until sources_failed is empty.
total_active counts the listings read for this answer, so total_active_is_minimum is always true: the marketplace may hold more, and marketplace_total gives its own figure where there is one. An identical search within 60 seconds is served from cache, and live_status says so per marketplace (ok_cached). cached and cached_age_s are eBay fields and read false and 0 here. With source=all the listings are interleaved so the first page shows every marketplace.
GET /v1/sources lists the sources with live listings under live_listings: all 12 marketplaces. psa is a sales record, so it has none, and /v1/active?source=psa returns 501.
Requests, limits and errors
One call is one request, whatever the source, and marketplace calls count against the same monthly quota as eBay calls. The per minute rate is the one on your plan: 120 requests a minute on paid plans, 10 on Free. Responses carry X-RateLimit-Limit, X-RateLimit-Remaining, X-Quota-Monthly and X-Quota-Used. Failed calls are not counted. Plans and quotas are in the main reference.
| Status | Meaning |
|---|---|
400 | Unknown source, missing q, q over 300 characters, a parameter that does not parse (min_price must be a number), a cursor from another search, or product_id, style_id or item_size on a source other than StockX and GOAT. |
401 | Missing or invalid key. |
403 | Key expired. |
404 | Unknown path. |
429 | rate_limited with retry_after and a Retry-After header, or quota_reached with your plan and monthly quota. |
500 | A problem on our side. Retry after a second or two. |
501 | not_available: live listings were asked for on a source that has none. |
Every error body is JSON with "ok": false and an error message, sometimes with a detail. /v1/cert, /v1/lookup and /v1/population can also answer 200 with "ok": false and error: psa_unavailable when PSA's data cannot be read at that moment. Those calls are not counted.