Whatnot

Whatnot active listings

Search 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/whatnot/listings

Request

  • Base URL: https://api.soldgraph.com/v1
  • URL: https://api.soldgraph.com/v1/whatnot/listings
  • Auth: HTTP bearer

Query parameters

qstring required

Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.

pageinteger

Source page to fetch. Where an endpoint has cursor, pages after 1 also need it.

min_priceinteger

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_priceinteger

Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price.

marketplace'whatnot'

Optional. If sent, it must be whatnot.

country'us' | 'ca'

Which country's sellers to search: us (US dollars) or ca (Canadian dollars). Results, prices, min_price and max_price use that country's currency. Optional.

countinteger

Most source rows per page. Whatnot can return fewer.

sort'best_match' | 'newest' | 'price_asc' | 'price_desc'

Source ranking, creation time descending, or asking price ascending/descending.

conditionstring

Exact case-sensitive seller attribute, such as Near Mint or Graded. Values vary by category.

categorystring

Whatnot category slug using lowercase letters, digits and underscores, such as pokemon_cards.

grading_servicestring

Exact case-sensitive seller-supplied grading service, such as PSA.

gradestring

Exact seller-supplied grade, such as 10. This is not certificate verification.

cursorstring

Previous page's next_cursor. Omit on page 1. Keep query, filters, sort and count unchanged.

Headers

Idempotency-Keystring

Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.

Response

Complete, including cache hits. Costs 1 request.

request_idstring required

ID of this request. Poll it at /v1/jobs/{request_id}.

status'pending' | 'complete' | 'failed' required

pending, complete or failed. Always check it, even on HTTP 200.

creditsinteger required

Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed.

cachedboolean required

True when the result came from the 15-minute cache.

poll_urlstring

Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL.

Changes

No recorded changes to this operation across all 1 revision of this API.