API overview

How Soldgraph routes work across resale listings and TCGplayer card products and recent sales, with jobs, caching, retries and pagination.

Base URL: https://api.soldgraph.com/v1. Send Authorization: Bearer <key> over HTTPS. Every route uses GET, except POST /v1/batches, which runs many searches in one call.

#Routes

GET /v1/ebay/soldeBay sold listingsSearch one page of eBay sold listings by keyword, on eBay US or seven other countries. A page holds up to 200 rows with count=200, or 40 without it. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/ebay/listingseBay active listingsSearch one page of eBay active listings by keyword, on eBay US or seven other countries, in the sort order you pick. A page holds up to 200 rows with count=200, or 40 without it. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/poshmark/soldPoshmark sold listingsSearch one page of Poshmark sold listings by keyword, on Poshmark US or Canada. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/poshmark/listingsPoshmark active listingsSearch one page of Poshmark active listings by keyword, on Poshmark US or Canada, in the sort order you pick. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/mercari/soldMercari sold listingsSearch one page of Mercari US sold listings by keyword, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/mercari/listingsMercari active listingsSearch one page of Mercari US active listings by keyword, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/depop/listingsDepop active listingsSearch one page of Depop active listings by keyword, from sellers in the US, UK, Australia or Canada, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.GET /v1/whatnot/listingsWhatnot active listingsSearch one page of Whatnot Buy It Now active listings from sellers in the US or Canada, up to 24 rows. Prices are seller asks. No sold search. Results are cached for 15 minutes; a cache miss returns 202 and a job to poll.GET /v1/tcgplayer/searchTCGplayer product searchSearch TCGplayer products by keyword; returns catalog identity, source market-price estimate and a few active seller asks. Cached 15 minutes; a cache miss returns 202 to poll.GET /v1/tcgplayer/salesTCGplayer recent salesFetch an exact product’s recent individual sales. Anonymous source access has shown at most five rows; this is not a complete sales history. Cached 15 minutes; a cache miss returns 202 to poll.GET /v1/offerup/listingsOfferUp local listingsSearch one page of OfferUp US active listings near a ZIP code or point, about 50 rows. Prices are seller asks. No sold search. Results are cached for 15 minutes; a cache miss returns 202 and a job to poll.GET /v1/offerup/itemOfferUp listing detailsFetch one OfferUp listing by ID or URL: description, posted date, condition, coordinates, shipping, photos, seller and vehicle details. Status is the seller-set state, not a verified sale. Cached 15 minutes; a cache miss returns 202 to poll.GET /v1/facebook/listingsFacebook local listingsSearch Facebook Marketplace US active listings near a ZIP code or point, up to about 24 rows. Prices are seller asks. No sold search. Results are cached for 15 minutes; a cache miss returns 202 and a job to poll.GET /v1/facebook/itemFacebook listing detailsFetch one Facebook Marketplace listing by ID or URL: description, condition, posted date, approximate coordinates, delivery and photos. Status is the seller-set state, not a verified sale. Cached 15 minutes; a cache miss returns 202 to poll.GET /v1/vinted/listingsVinted active listingsSearch one page of Vinted active listings by keyword, on Vinted US, UK or 24 European sites, 96 rows a page. Prices are seller asks. No sold search. Results are cached for 15 minutes; a cache miss returns 202 and a job to poll.GET /v1/vinted/itemVinted listing detailsFetch one Vinted listing by ID or URL: description, condition, brand, size, colour, category, photos and the seller's rating. Status is not a verified sale. Cached 15 minutes; a cache miss returns 202 to poll.

Listing searches accept these shared parameters. TCGplayer product search accepts q, page, country and optional count; TCGplayer recent sales accepts an exact numeric product ID in q and optional country.

ParameterTypeDefaultDescription
qstringRequiredSearch keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.
pageinteger, 1–1001Source page to fetch. Where an endpoint has cursor, pages after 1 also need it.
min_priceinteger, 0–1000000Lowest price, in whole units of the country's currency (US dollars for us). Optional. Must not be more than max_price. You can send it without max_price.
max_priceinteger, 0–1000000Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price.
marketplacestringOptional. If sent, it must match the marketplace in the path.
countryususOnly us is supported here. eBay, Vinted, Poshmark, Depop and Whatnot endpoints also take other countries. Mercari, OfferUp, Facebook Marketplace and TCGplayer are US only.

Some routes add their own, like condition, sort and cursor. See Search inputs.

#Search jobs

A search either returns its result right away or gives you a job to poll.

  1. Send the search. A cached result returns 200 with status: "complete". Otherwise you get 202 with status: "pending", a poll_url and a Retry-After: 2 header.
  2. Poll the job. Call poll_url with the same API key and add ?wait=20. The server holds the call open for up to 20 seconds and answers as soon as the job finishes. This is called long-polling. You don't need to sleep between polls.
  3. Check status. A job poll returns 200 whether the job is pending, complete or failed. If it's still pending, poll again.
Poll a job
curl "https://api.soldgraph.com/v1/jobs/REQUEST_ID?wait=20" \  -H "Authorization: Bearer $SOLDGRAPH_KEY"

A complete job has result. A failed job has error.code and costs nothing. See failed job codes. Only the 202 response has a Retry-After header. Job polls don't.

#Caching and cost

Matching searches share a 15-minute cache. The cached field tells you if yours used it.

A complete search costs 1 request from your allowance, including a cache hit. Failed searches and job polls cost nothing. While a search is pending, it holds 1 request of your allowance. If the job fails, you get it back. See Usage and billing.

Each account can have only a limited number of searches pending at once. See Rate limits.

#Many searches at once

To run a list of searches, send them as one batch. You poll one ID, get a price summary per search, and can download every row as CSV. Each search in a batch costs the same as sending it alone.

Add ?format=csv to a finished job's poll URL to get its rows as a CSV file.

#Retries and Idempotency-Key

Send an Idempotency-Key header with each search, like a UUID. If a call fails and you retry with the same key and parameters, you get the same request back. You aren't charged twice.

  • Reusing a key with different parameters returns 409 idempotency_conflict.
  • A key is 1–128 printable ASCII characters, with no spaces.
  • Without the header, every call is a new request.
  • Retrying a failed search with the same key returns that failed job again: HTTP 503, or a 4xx when the search itself caused the failure (see failed job codes). To try again, use a new key.

#Pagination

Every search result has next_page and next_cursor. To get the next page where supported, send the same search with page set to next_page. Keep every other parameter the same. When next_cursor is not null, send cursor set to it too. Poshmark, Mercari, Depop, Whatnot and OfferUp use cursors. eBay, Vinted and TCGplayer product search use page numbers. Vinted stops at page 10. Facebook local listings have one page. TCGplayer recent sales is an unpaged sample. When next_page is null, there is no next page available.

The same listing or product can show up on more than one page. Deduplicate listing pages by id and TCGplayer search pages by product_id.

#Request IDs

Every response has an X-Request-Id header. Include it when you contact support.

#Legacy paths

/v1/sold and /v1/listings are old paths for /v1/ebay/sold and /v1/ebay/listings. They share the same cache, billing and idempotency keys, with no redirect. They still work, but use the marketplace paths in new code.

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