--- title: "eBay active listings" method: GET path: "/ebay/listings" tags: ["eBay"] --- # eBay active listings `GET /ebay/listings` ## Request - Base URL: `https://api.soldgraph.com/v1` - URL: `https://api.soldgraph.com/v1/ebay/listings` - Auth: HTTP bearer Search one page of eBay active listings by keyword, on eBay US or seven other countries, in the sort order you pick. A page holds up to 200 rows with count=200, or 40 without it. 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` 'ebay' - `country` 'us' | 'uk' | 'ca' | 'au' | 'de' | 'fr' | 'it' | 'es' - `sort` 'best_match' | 'newest' | 'price_asc' | 'ending_soon' - `condition` string[] - `item_location` 'domestic' | 'worldwide' - `buying_format` 'auction' | 'buy_it_now' | 'best_offer' - `count` 40 | 60 | 120 | 200 - `category_id` integer ## Headers - `Idempotency-Key` string ## Response `200` Complete, including cache hits. Costs 1 request. - EbayListingsJob - `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` EbayListingsPage - `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, required: Total matches the marketplace reports for the search. It may be rounded or capped. - `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. - `next_cursor` unknown, required - `page_size` integer, required: Rows per page, as eBay reports it. - `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 a price range or an unread price are left out of the maths. - `priced_count` integer, required: Rows on this page that show one price in the site's currency. - `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. - `data` EbayListingsRow[], required - `id` string, required: The marketplace's listing ID. - `title` string, nullable, required: Listing title as shown. - `link` string, required: URL of the listing on the eBay site you searched, like https://www.ebay.co.uk/itm/…. - `promoted` boolean, required: True for a sponsored placement. - `format` string, required: auction when the listing shows bids or an end time, otherwise fixed_price. - `displayed_price` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `displayed_price_text` string, nullable, required: The price text as shown, like $189.00, £124.46 or €230.00. - `displayed_price_range` object, nullable, required: { low, high, currency } when eBay shows a price range for a multi-variation listing ("$247.00 to $911.00"). Null otherwise. displayed_price is null for these rows, so they stay out of the summary maths. - `low` number, required - `high` number, required - `currency` string, required: ISO 4217 code, like USD. - `displayed_shipping` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `shipping_text` string, nullable, required: Shipping text as shown, like +$9.99 delivery, Free delivery or + €10.49 de envío. - `condition` string, nullable, required: eBay's condition text as shown, in the site's language, like Pre-Owned, Pre-owned or Gebraucht. To filter by condition in any language, use condition. - `bid_count` integer, nullable, required: Number of bids, for auctions. - `ends_at` string, nullable, required: Auction end time, ISO 8601 UTC. - `best_offer` boolean, required: True when the seller accepts Best Offers. - `seller_text` string, nullable, required: Seller text as eBay shows it: username, feedback count and positive percentage, e.g. clutch_supply (1,325) 99.7%. - `location_text` string, nullable, required: Item location text as shown. - `image` string, nullable, required: Image URL on i.ebayimg.com. - `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)