--- title: "Whatnot active listings" method: GET path: "/whatnot/listings" tags: ["Whatnot"] --- # Whatnot active listings `GET /whatnot/listings` ## Request - Base URL: `https://api.soldgraph.com/v1` - URL: `https://api.soldgraph.com/v1/whatnot/listings` - Auth: HTTP bearer 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. ## Query parameters - `q` string, required - `page` integer - `min_price` integer - `max_price` integer - `marketplace` 'whatnot' - `country` 'us' | 'ca' - `count` integer - `sort` 'best_match' | 'newest' | 'price_asc' | 'price_desc' - `condition` string - `category` string - `grading_service` string - `grade` string - `cursor` string ## Headers - `Idempotency-Key` string ## Response `200` Complete, including cache hits. Costs 1 request. - WhatnotListingsJob - `request_id` string, 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. - `credits` integer, required: Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. - `cached` boolean, required: True when the result came from the 15-minute cache. - `poll_url` string: Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL. - `result` WhatnotListingsPage - `provider` string, required: Marketplace ID, like ebay or poshmark. - `country` string, required: The country searched: us, or on eBay the country you sent. - `query` string, required: The q you sent, with extra spaces removed. - `page` integer, required: The page you asked for. - `count` integer, required: Rows in result.data on this page. - `reported_total` integer, nullable, required: Always null: no reliable total is provided by this search. - `next_page` integer, nullable, required: Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served. - `collected_at` string, required: When we collected the page, as an ISO 8601 timestamp. - `schema_version` integer, required: Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning. - `completeness` string, required: provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only. - `field_notes` string, required: Plain-text notes on how to read this page's fields. - `page_size` integer, required: Source rows, including non-listing text dividers, before excluding unavailable inventory, sellers in another country and prices in another currency. - `summary` object, required: 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. - `priced_count` integer, required: Rows on this page that show one price. - `currency` string, required: Currency of the amounts below. - `median` number, nullable, required: Middle displayed price of those rows. - `low` number, nullable, required: Lowest displayed price. - `high` number, nullable, required: Highest displayed price. - `p25` number, nullable, required: First-quartile displayed price: a quarter of priced rows are at or below it. - `p75` number, nullable, required: Third-quartile displayed price. With `p25`, a range that ignores a stray accessory or parts listing. - `next_cursor` string, nullable, required: Send as cursor with page=next_page. Null at the end. - `data` WhatnotListingsRow[], required - `id` string, required: Whatnot opaque listing ID; use it to deduplicate across pages. - `title` string, required: Seller title, up to 2,000 characters. - `link` string, required: Public Whatnot listing URL. - `displayed_price` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `displayed_price_text` string, nullable, required: Formatted asking price or variant range, like $40.00 or C$189.00. - `condition` string, nullable, required: Seller-supplied condition, when present. - `image` string, nullable, required: Primary image on the Whatnot image CDN. - `quantity` integer, required: Available quantity reported by the source at collection time. - `listed_at` string, nullable, required: Source creation timestamp in UTC, when present. Not a sale timestamp. - `seller_text` string, nullable, required: Public seller username. - `grading_service` string, nullable, required: Seller-supplied grading service; not independently verified. - `grade` string, nullable, required: Seller-supplied grade; not independently verified. - `card_set` string, nullable, required: Seller-supplied card set, when present. - `card_number` string, nullable, required: Seller-supplied card number, when present. - `language` string, nullable, required: Seller-supplied language, when present. - `error` object - `code` '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', required: Failed job code. - `message` string: What the code means, in plain words. ## Other responses - `202`: Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com. - `401`: invalid_api_key: The API key is missing, malformed or revoked. - `403`: 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. - `404`: 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. - `405`: method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST. - `409`: 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. - `413`: payload_too_large: The batch body is over 256 KB. - `414`: uri_too_long: The query string is longer than 2,048 characters. - `415`: unsupported_media_type: A batch must be sent as Content-Type: application/json. - `422`: 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. - `429`: 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. - `503`: 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. --- [API](https://skmtc.dev/soldgraph/apis/soldgraph-api.md) · [All operations](https://skmtc.dev/soldgraph/apis/soldgraph-api/llms.txt) · [OpenAPI document](https://skmtc.dev/soldgraph/apis/soldgraph-api/revisions/137f0810f983?raw)