Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: Soldgraph Whatnot API
version: 1.0.0
description: Resale listings from eight marketplaces (eBay in 8 countries; Vinted in the US, UK and 24 European countries; Poshmark and Whatnot in the US and Canada; Depop in the US, UK, Australia and Canada; the rest US), plus TCGplayer product search and recent card sales.
contact:
url: https://soldgraph.com/docs
servers:
- url: https://api.soldgraph.com/v1
security:
- bearer: []
tags:
- name: Whatnot
paths:
/whatnot/listings:
get:
operationId: whatnot_listings
tags:
- Whatnot
summary: Whatnot active listings
description: 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.
externalDocs:
url: https://soldgraph.com/docs/api/whatnot-listings
parameters:
- name: q
in: query
required: true
description: 'Search keywords, 1–200 characters, as you''d type them into the marketplace''s search box. Be specific: model, size, grade, edition.'
schema:
type: string
minLength: 1
maxLength: 200
- name: page
in: query
required: false
description: Source page to fetch. Where an endpoint has cursor, pages after 1 also need it.
schema:
type: integer
minimum: 1
maximum: 100
default: 1
- name: min_price
in: query
required: false
description: 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.
schema:
type: integer
minimum: 0
maximum: 1000000
- name: max_price
in: query
required: false
description: Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price.
schema:
type: integer
minimum: 0
maximum: 1000000
- name: marketplace
in: query
required: false
description: Optional. If sent, it must be whatnot.
schema:
type: string
enum:
- whatnot
default: whatnot
- name: country
in: query
required: false
description: '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.'
schema:
type: string
enum:
- us
- ca
default: us
- name: count
in: query
required: false
description: Most source rows per page. Whatnot can return fewer.
schema:
type: integer
minimum: 1
maximum: 24
default: 24
- name: sort
in: query
required: false
description: Source ranking, creation time descending, or asking price ascending/descending.
schema:
type: string
enum:
- best_match
- newest
- price_asc
- price_desc
default: best_match
- name: condition
in: query
required: false
description: Exact case-sensitive seller attribute, such as Near Mint or Graded. Values vary by category.
schema:
type: string
minLength: 1
maxLength: 100
- name: category
in: query
required: false
description: Whatnot category slug using lowercase letters, digits and underscores, such as pokemon_cards.
schema:
type: string
minLength: 1
maxLength: 100
- name: grading_service
in: query
required: false
description: Exact case-sensitive seller-supplied grading service, such as PSA.
schema:
type: string
minLength: 1
maxLength: 100
- name: grade
in: query
required: false
description: Exact seller-supplied grade, such as 10. This is not certificate verification.
schema:
type: string
minLength: 1
maxLength: 40
- name: cursor
in: query
required: false
description: Previous page's next_cursor. Omit on page 1. Keep query, filters, sort and count unchanged.
schema:
type: string
minLength: 1
maxLength: 2048
- name: Idempotency-Key
in: header
required: false
description: Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.
schema:
type: string
pattern: ^[!-~]{1,128}$
responses:
'200':
description: Complete, including cache hits. Costs 1 request.
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/WhatnotListingsJob'
example:
request_id: example-whatnot-search
status: complete
credits: 1
cached: false
result:
provider: whatnot
country: us
query: pokemon
page: 1
page_size: 5
count: 5
reported_total: null
next_page: 2
next_cursor: WyJZWEp5WVhsamIyNXVaV04wYVc5dU9qUT0iLCAiNzhjYWUyNDhkM2FiZDVlOGFhY2UxZWNlMjg1ZjljZDZmY2I0YTBjZjkzNmYzMjgwZGU0ZmUwMTU5OGMzODc0OSIsIDJd
collected_at: '2026-10-01T03:22:12.992189+00:00'
schema_version: 2
completeness: provider_page_only
summary:
priced_count: 5
currency: USD
median: 50
low: 30
high: 160
p25: 39
p75: 65
data:
- id: TGlzdGluZ05vZGU6MjM2MDA2ODU0Mg==
title: 'Pokemon TCG: Scarlet & Violet-Surging Sparks Pokemon Center Elite Trainer Box'
link: https://www.whatnot.com/listing/TGlzdGluZ05vZGU6MjM2MDA2ODU0Mg==
displayed_price:
amount: 160
currency: USD
displayed_price_text: $160.00
condition: New
image: https://images.whatnot.com/eyJidWNrZXQiOiAid2hhdG5vdC1pbWFnZXMiLCAia2V5IjogImxpc3RpbmdzLzAtZDU4MDhkZWEtZDA5OS00MzFkLWI0YWMtNDQyNWU5MGE4NDJlLWIxMGJhM2FmLTU3NWQtNGJiZC04NWJkLTkxZjFlODgzMjI1MC5qcGVnIiwgImVkaXRzIjogeyJyZXNpemUiOiB7IndpZHRoIjogbnVsbCwgImhlaWdodCI6IG51bGwsICJmaXQiOiAiY29udGFpbiIsICJiYWNrZ3JvdW5kIjogeyJyIjogMjU1LCAiZyI6IDI1NSwgImIiOiAyNTUsICJhbHBoYSI6IDF9fX19?signature=2e96ba9b90cffd216782b8ff8036bcce4db5a910e06b008e834a055d91f7bb58
quantity: 1
listed_at: '2026-09-27T23:08:08+00:00'
seller_text: aws20
grading_service: null
grade: null
card_set: Surging Sparks
card_number: null
language: English
- id: TGlzdGluZ05vZGU6MjM3MTYyMzgzNA==
title: Pokemon Zorua Plush
link: https://www.whatnot.com/listing/TGlzdGluZ05vZGU6MjM3MTYyMzgzNA==
displayed_price:
amount: 30
currency: USD
displayed_price_text: $30.00
condition: New
image: https://images.whatnot.com/eyJidWNrZXQiOiAid2hhdG5vdC1pbWFnZXMiLCAia2V5IjogImxpc3RpbmdzLzAtYjMyNjExNDAtODAzNy00ZTA1LTgyZGEtYmNlOTliZWVjNTEyLWVmZTc4MDI5LTg5YmItNGViMy04OTZmLWU1MWMyNTdiNGU1ZS5qcGVnIiwgImVkaXRzIjogeyJyZXNpemUiOiB7IndpZHRoIjogbnVsbCwgImhlaWdodCI6IG51bGwsICJmaXQiOiAiY29udGFpbiIsICJiYWNrZ3JvdW5kIjogeyJyIjogMjU1LCAiZyI6IDI1NSwgImIiOiAyNTUsICJhbHBoYSI6IDF9fX19?signature=75a21ade4834c9a03f58eed943bce7b7ee6c37c2be04bfcf87669427beaa9346
quantity: 1
listed_at: '2026-09-29T21:59:36+00:00'
seller_text: mandobrix1
grading_service: null
grade: null
card_set: null
card_number: null
language: null
- id: TGlzdGluZ05vZGU6MjM2MjY1MjAxOQ==
title: Gameboy Pokemon Red
link: https://www.whatnot.com/listing/TGlzdGluZ05vZGU6MjM2MjY1MjAxOQ==
displayed_price:
amount: 65
currency: USD
displayed_price_text: $65.00
condition: null
image: https://images.whatnot.com/eyJidWNrZXQiOiAid2hhdG5vdC1pbWFnZXMiLCAia2V5IjogImxpc3RpbmdzLzAtYTExNGVlMzktZWQ1Ny00ZDZlLWI5OTYtNjhhNTc4NDMxNDZiLTU2MzUxZTkyLTMxZGUtNGI5My1iZDUwLTFmZjc2M2ZhOWMyZC5qcGVnIiwgImVkaXRzIjogeyJyZXNpemUiOiB7IndpZHRoIjogbnVsbCwgImhlaWdodCI6IG51bGwsICJmaXQiOiAiY29udGFpbiIsICJiYWNrZ3JvdW5kIjogeyJyIjogMjU1LCAiZyI6IDI1NSwgImIiOiAyNTUsICJhbHBoYSI6IDF9fX19?signature=6081840124ba0c0a6befaf15c67bc32e11c6fb76b7be83ed73a552f6376f2f4b
quantity: 1
listed_at: '2026-09-28T18:05:46+00:00'
seller_text: retrokart89
grading_service: null
grade: null
card_set: null
card_number: null
language: null
- id: TGlzdGluZ05vZGU6MjMxNDQyNTI2Nw==
title: Nintendo 3DS Pokemon Ultra Moon
link: https://www.whatnot.com/listing/TGlzdGluZ05vZGU6MjMxNDQyNTI2Nw==
displayed_price:
amount: 50
currency: USD
displayed_price_text: $50.00
condition: null
image: https://images.whatnot.com/eyJidWNrZXQiOiAid2hhdG5vdC1pbWFnZXMiLCAia2V5IjogImxpc3RpbmdzLzAtNDMwNGFkYmQtZjkxNi00ZmU4LTg1ZGItNTAzZjU5Y2VjNjY3LTdlNzYyNmVmLWI4NWYtNDMyMC05ODZmLTg1NDA5MDhmNzE5MS5qcGVnIiwgImVkaXRzIjogeyJyZXNpemUiOiB7IndpZHRoIjogbnVsbCwgImhlaWdodCI6IG51bGwsICJmaXQiOiAiY29udGFpbiIsICJiYWNrZ3JvdW5kIjogeyJyIjogMjU1LCAiZyI6IDI1NSwgImIiOiAyNTUsICJhbHBoYSI6IDF9fX19?signature=5fecd8c810e8d929390dbda929dc877d134686b3a5e168983f6951d3127e1991
quantity: 1
listed_at: '2026-09-16T22:43:38+00:00'
seller_text: retrokart89
grading_service: null
grade: null
card_set: null
card_number: null
language: null
- id: TGlzdGluZ05vZGU6MjMzMzA1MTI2MQ==
title: Bigpapa's Pokemon RGB Lamp ( w/Remote and charging cord )
link: https://www.whatnot.com/listing/TGlzdGluZ05vZGU6MjMzMzA1MTI2MQ==
displayed_price:
amount: 39
currency: USD
displayed_price_text: $39.00
condition: null
image: https://images.whatnot.com/eyJidWNrZXQiOiAid2hhdG5vdC1pbWFnZXMiLCAia2V5IjogImxpc3RpbmdzLzAtMzAzZTg5NjctODljZS00OWZlLTk2M2UtOWY0NTNmZGZmNDlmLTYyZTgzOGY2LTVkNmEtNGJiMC05YmJkLTE1ZDJkZGY1MmRkNy5qcGVnIiwgImVkaXRzIjogeyJyZXNpemUiOiB7IndpZHRoIjogbnVsbCwgImhlaWdodCI6IG51bGwsICJmaXQiOiAiY29udGFpbiIsICJiYWNrZ3JvdW5kIjogeyJyIjogMjU1LCAiZyI6IDI1NSwgImIiOiAyNTUsICJhbHBoYSI6IDF9fX19?signature=8d98d8e780f4bdebe74eda82f0616c7182c29162501dd4dd96648869511cdf20
quantity: 1
listed_at: '2026-09-21T03:29:04+00:00'
seller_text: big_papa_308
grading_service: null
grade: null
card_set: null
card_number: null
language: null
field_notes: Active US Buy It Now listings priced in USD. Displayed prices are seller asks, excluding shipping and checkout charges; they are not transaction prices. Unequal variant ranges have no single displayed_price. Attributes and grades are seller supplied, not independently verified. One source page, not complete coverage; ranking can repeat listings between pages or broaden keyword matches. No public sold search or final sale prices are provided.
'202':
description: 'Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Location:
description: Job path, like /v1/jobs/{id}.
schema:
type: string
Retry-After:
description: Always 2. Prefer long-polling with ?wait=20.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/WhatnotListingsJob'
example:
request_id: 00000000-0000-4000-8000-000000000001
status: pending
credits: 0
cached: false
poll_url: /v1/jobs/00000000-0000-4000-8000-000000000001
'401':
description: 'invalid_api_key: The API key is missing, malformed or revoked.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'403':
description: 'account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn''t allowed. Call the API from your server.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'404':
description: 'not_found: No such path. request_not_found: The job ID is well-formed but unknown, or belongs to another account. An ID that isn''t a UUID is no such path: 404 not_found. batch_not_found: No batch with that ID belongs to this account. Or a replay of a search that failed because of the search (the body is then the failed job): not_found.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/WhatnotListingsJob'
'405':
description: 'method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: 'idempotency_conflict: This Idempotency-Key was already used with different search parameters. result_not_ready: CSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'413':
description: 'payload_too_large: The batch body is over 256 KB.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'414':
description: 'uri_too_long: The query string is longer than 2,048 characters.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
description: 'unsupported_media_type: A batch must be sent as Content-Type: application/json.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'422':
description: 'unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. error.param names the input to fix when it is one of the route''s inputs. duplicate_parameter: A parameter was sent more than once. sort_not_implemented: sort=best_deal is not available. invalid_idempotency_key: Idempotency-Key must be 1–128 printable ASCII characters, with no spaces. invalid_wait: wait must be a whole number from 0 to 20. invalid_body: The batch body is not JSON, or has no searches list. batch_too_large: The batch holds more searches than your plan allows at once. pages counts as one search per page. invalid_format: format must be json or csv, and include must be results. Or a replay of a search that failed because of the search (the body is then the failed job): rejected, filter_not_supported, filter_not_applied, location_not_served.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/WhatnotListingsJob'
'429':
description: 'rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan''s allowance is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'503':
description: 'Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace''s daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can''t collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn''t reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.'
headers:
X-Request-Id:
description: Unique ID for this response. Include it when you contact support.
schema:
type: string
Retry-After:
description: Seconds to wait before retrying.
schema:
type: integer
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/Error'
- $ref: '#/components/schemas/WhatnotListingsJob'
components:
schemas:
Money:
type: object
required:
- amount
- currency
properties:
amount:
type: number
currency:
type: string
description: ISO 4217 code, like USD.
WhatnotListingsPage:
type: object
required:
- provider
- country
- query
- page
- count
- reported_total
- next_page
- collected_at
- schema_version
- completeness
- field_notes
- page_size
- summary
- next_cursor
- reported_total
- data
properties:
provider:
type: string
description: Marketplace ID, like ebay or poshmark.
country:
type: string
description: 'The country searched: us, or on eBay the country you sent.'
query:
type: string
description: The q you sent, with extra spaces removed.
page:
type: integer
description: The page you asked for.
count:
type: integer
description: Rows in result.data on this page.
reported_total:
type:
- integer
- 'null'
description: 'Always null: no reliable total is provided by this search.'
next_page:
type:
- integer
- 'null'
description: Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served.
collected_at:
type: string
description: When we collected the page, as an ISO 8601 timestamp.
schema_version:
type: integer
description: 'Version of the result''s shape for that marketplace: 1 or 2. It only rises when a field changes meaning.'
completeness:
type: string
description: 'provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only.'
field_notes:
type: string
description: Plain-text notes on how to read this page's fields.
page_size:
type: integer
description: Source rows, including non-listing text dividers, before excluding unavailable inventory, sellers in another country and prices in another currency.
summary:
type: object
properties:
priced_count:
type: integer
description: Rows on this page that show one price.
currency:
type: string
description: Currency of the amounts below.
median:
type:
- number
- 'null'
description: Middle displayed price of those rows.
low:
type:
- number
- 'null'
description: Lowest displayed price.
high:
type:
- number
- 'null'
description: Highest displayed price.
p25:
type:
- number
- 'null'
description: 'First-quartile displayed price: a quarter of priced rows are at or below it.'
p75:
type:
- number
- 'null'
description: Third-quartile displayed price. With `p25`, a range that ignores a stray accessory or parts listing.
required:
- priced_count
- currency
- median
- low
- high
- p25
- p75
description: 'Price maths over the rows on this page: priced_count, currency, median, low, high. No row is removed from data. Rows with no single readable price are left out of the maths.'
next_cursor:
type:
- string
- 'null'
description: Send as cursor with page=next_page. Null at the end.
data:
type: array
items:
$ref: '#/components/schemas/WhatnotListingsRow'
Error:
type: object
required:
- error
properties:
error:
type: object
required:
- code
properties:
code:
type: string
enum:
- invalid_api_key
- account_suspended
- origin_not_allowed
- not_found
- request_not_found
- batch_not_found
- method_not_allowed
- idempotency_conflict
- result_not_ready
- payload_too_large
- uri_too_long
- unsupported_media_type
- unsupported_or_invalid_query
- duplicate_parameter
- sort_not_implemented
- invalid_idempotency_key
- invalid_wait
- invalid_body
- batch_too_large
- invalid_format
- rate_limited
- quota_exceeded
- too_many_pending
- upstream_daily_limit
- queue_full
- collection_unavailable
- storage_unavailable
- origin_unavailable
- service_unconfigured
message:
type: string
description: What the code means, in plain words. On every error; safe to show to a user.
param:
type: string
description: 'On a 422: the input to fix, when it is one of the route''s inputs. Never a value.'
index:
type: integer
description: 'On a refused batch: the position of the search to fix.'
upgrade_url:
type: string
format: uri
description: 'On quota_exceeded: the billing page, where you move to a larger plan or buy extra requests.'
WhatnotListingsJob:
type: object
required:
- request_id
- status
- credits
- cached
properties:
request_id:
type: string
description: ID of this request. Poll it at /v1/jobs/{request_id}.
status:
type: string
description: pending, complete or failed. Always check it, even on HTTP 200.
enum:
- pending
- complete
- failed
credits:
type: integer
description: 'Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed.'
cached:
type: boolean
description: True when the result came from the 15-minute cache.
poll_url:
type: string
description: 'Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL.'
result:
$ref: '#/components/schemas/WhatnotListingsPage'
error:
type: object
required:
- code
properties:
code:
type: string
enum:
- page_mismatch
- schema
- network
- upstream
- throttled
- blocked
- rejected
- not_found
- filter_not_supported
- filter_not_applied
- location_not_served
- auth
- daily_limit
- deadline_exceeded
- credential_storage
description: Failed job code.
message:
type: string
description: What the code means, in plain words.
WhatnotListingsRow:
type: object
required:
- id
- title
- link
- displayed_price
- displayed_price_text
- condition
- image
- quantity
- listed_at
- seller_text
- grading_service
- grade
- card_set
- card_number
- language
properties:
id:
type: string
description: Whatnot opaque listing ID; use it to deduplicate across pages.
title:
type: string
description: Seller title, up to 2,000 characters.
link:
type: string
description: Public Whatnot listing URL.
displayed_price:
oneOf:
- $ref: '#/components/schemas/Money'
- type: 'null'
description: Asking price as { amount, currency } in the country's currency, excluding shipping and checkout charges. Null for an unequal variant range or an absent source price. Never a transaction price.
displayed_price_text:
type:
- string
- 'null'
description: Formatted asking price or variant range, like $40.00 or C$189.00.
condition:
type:
- string
- 'null'
description: Seller-supplied condition, when present.
image:
type:
- string
- 'null'
description: Primary image on the Whatnot image CDN.
quantity:
type: integer
description: Available quantity reported by the source at collection time.
listed_at:
type:
- string
- 'null'
description: Source creation timestamp in UTC, when present. Not a sale timestamp.
seller_text:
type:
- string
- 'null'
description: Public seller username.
grading_service:
type:
- string
- 'null'
description: Seller-supplied grading service; not independently verified.
grade:
type:
- string
- 'null'
description: Seller-supplied grade; not independently verified.
card_set:
type:
- string
- 'null'
description: Seller-supplied card set, when present.
card_number:
type:
- string
- 'null'
description: Seller-supplied card number, when present.
language:
type:
- string
- 'null'
description: Seller-supplied language, when present.
securitySchemes:
bearer:
type: http
scheme: bearer
description: An API key from the Soldgraph dashboard, starting with sg_.