Docs
DashboardGet API key
API reference

API overview

How the Soldgraph API works: base URL, search routes for eBay, Poshmark, Mercari and Depop, search jobs, caching, retries and pagination.

Base URL: https://api.soldgraph.com/v1. Send Authorization: Bearer <key> over HTTPS. Every route uses GET.

#Routes

GET /v1/ebay/soldeBay sold listingsSearch one page of eBay US sold listings by keyword. 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 US active listings by keyword, in the sort order you pick. 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 US sold listings by keyword. 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 US active listings by keyword, 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 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.

Every search route accepts these parameters:

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. On Poshmark, Mercari and Depop, pages after 1 also need cursor.
min_priceinteger, 0–1000000Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.
max_priceinteger, 0–1000000Highest price, in whole US dollars. Optional. You can send it without min_price.
marketplacestringOptional. If sent, it must match the marketplace in the path: ebay, poshmark, mercari or depop.
countryususOnly us is supported.

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.

#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, with HTTP 503. To try again, use a new key.

#Pagination

Every result has next_page. To get the next page, send the same search with page set to next_page. Keep every other parameter the same. If the result also has next_cursor, send cursor set to next_cursor too. Poshmark, Mercari and Depop use cursors. eBay doesn't. When next_page is null, you're on the last page.

The same listing can show up on more than one page. Deduplicate by id when you combine pages.

#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.