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
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.
| Parameter | Type | Default | Description |
|---|---|---|---|
q | string | Required | Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition. |
page | integer, 1–100 | 1 | Source page to fetch. Where an endpoint has cursor, pages after 1 also need it. |
min_price | integer, 0–1000000 | Lowest 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_price | integer, 0–1000000 | Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price. | |
marketplace | string | Optional. If sent, it must match the marketplace in the path. | |
country | us | us | Only 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.
- Send the search. A cached result returns 200 with
status: "complete". Otherwise you get 202 withstatus: "pending", apoll_urland aRetry-After: 2header. - Poll the job. Call
poll_urlwith 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. - Check
status. A job poll returns 200 whether the job ispending,completeorfailed. If it's stillpending, poll again.
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