{ "openapi": "3.0.3", "info": { "title": "CompSniper Marketplace and Shipping APIs", "version": "2.1.1", "description": "Public eBay (including up to 3 years of sold history), Poshmark, Mercari, and TCGplayer marketplace data plus a separate quote-only US shipping-rates product. Shipping quotes separate applicable services from carrier-packaging and content-restricted options, use an independent subscription and quota, and do not consume sold-comps requests or purchased credits.", "contact": { "name": "CompSniper", "url": "https://compsniper.com" } }, "servers": [ { "url": "https://api.compsniper.com" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/research/sold": { "get": { "tags": [ "Sold history" ], "summary": "Search up to 3 years of eBay sold history", "description": "Keyword search over eBay sold history going back up to 3 years (eBay's own limit), across eight eBay sites, on every plan including free. Each page of up to 50 listing-level rows uses one request; failed requests are free. Prices are USD. History has its own cap of 20 searches per minute per account (X-History-RateLimit-* headers, 429 history_rate_limited), on top of the plan limit.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1, "maxLength": 200, "example": "nintendo switch oled", "description": "Search term" } }, { "name": "startDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2023-10-11", "description": "First day (YYYY-MM-DD), no earlier than 3 years before today" } }, { "name": "endDate", "in": "query", "required": true, "schema": { "type": "string", "format": "date", "example": "2026-10-10", "description": "Last day (YYYY-MM-DD), no later than today (UTC)" } }, { "name": "ebaySite", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.com.au", "ebay.ca", "ebay.de", "ebay.fr", "ebay.it", "ebay.es" ], "default": "ebay.com", "description": "eBay marketplace" } }, { "name": "sort", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "quantityAscending", "lastSoldDescending" ], "default": "quantityAscending", "description": "lastSoldDescending = newest sale first" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "enum": [ 10, 20, 50 ], "default": 50, "description": "Rows per page" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 1, "description": "Page number" } }, { "name": "singleUnitOnly", "in": "query", "required": false, "schema": { "type": "boolean", "default": false, "description": "Only listings that sold exactly one unit" } } ], "responses": { "200": { "description": "Sold history page", "content": { "application/json": { "schema": { "type": "object", "properties": { "source": { "type": "string", "example": "ebay_product_research" }, "ebaySite": { "type": "string" }, "displayCurrency": { "type": "string", "example": "USD" }, "startDate": { "type": "string" }, "endDate": { "type": "string" }, "page": { "type": "integer" }, "limit": { "type": "integer" }, "sourceResultCount": { "type": "integer" }, "resultCount": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "nextPage": { "type": "integer", "nullable": true }, "relevanceApplied": { "type": "boolean", "example": false }, "warnings": { "type": "array", "items": { "type": "string" } }, "requestId": { "type": "string" }, "results": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string", "example": "267809186741" }, "title": { "type": "string", "nullable": true }, "extendedTitle": { "type": "string", "nullable": true }, "itemUrl": { "type": "string", "nullable": true }, "imageUrl": { "type": "string", "nullable": true }, "recordType": { "type": "string", "enum": [ "single_unit_listing", "listing_aggregate" ] }, "soldUnits": { "type": "integer", "example": 1 }, "averageSoldPrice": { "type": "object", "nullable": true, "properties": { "amount": { "type": "string", "example": "184.00" }, "currency": { "type": "string", "example": "USD" }, "display": { "type": "string", "example": "$ 184.00" } } }, "totalSales": { "type": "object", "nullable": true, "properties": { "amount": { "type": "string", "example": "184.00" }, "currency": { "type": "string", "example": "USD" }, "display": { "type": "string", "example": "$ 184.00" } } }, "averageShipping": { "type": "object", "nullable": true, "properties": { "amount": { "type": "string", "example": "184.00" }, "currency": { "type": "string", "example": "USD" }, "display": { "type": "string", "example": "$ 184.00" } } }, "soldPrice": { "type": "object", "nullable": true, "properties": { "amount": { "type": "string", "example": "184.00" }, "currency": { "type": "string", "example": "USD" }, "display": { "type": "string", "example": "$ 184.00" } } }, "soldDate": { "type": "string", "nullable": true, "example": "2026-10-09" }, "lastSoldDate": { "type": "string", "example": "2026-10-09" }, "listingFormat": { "type": "string", "nullable": true, "example": "Fixed price" }, "bids": { "type": "integer", "nullable": true }, "condition": { "type": "string", "nullable": true }, "conditionId": { "type": "integer", "nullable": true } } } } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } } } } }, "/v1/tcgplayer/sold": { "get": { "tags": [ "TCGplayer" ], "summary": "TCGplayer completed sales and price history", "description": "Full TCGplayer completed-sale history for a product, with optional market price history. One successful call uses one request; identical calls within 24 hours return the saved result.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "example": "charizard ex obsidian flames 223", "description": "Card or product name (required unless productId is sent)" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Exact TCGplayer product ID" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 250, "default": 100, "description": "Number of sales" } }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "example": "Near Mint", "description": "Condition filter" } }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "example": "Holofoil", "description": "Variant filter" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "example": "English", "description": "Language filter" } }, { "name": "history", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "none", "month", "quarter", "annual" ], "default": "none", "description": "Market price history range" } } ], "responses": { "200": { "description": "Sales", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string" }, "marketplace": { "type": "string", "example": "tcgplayer" }, "product": { "type": "object", "nullable": true, "properties": { "productId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "productLine": { "type": "string", "nullable": true }, "setName": { "type": "string", "nullable": true }, "number": { "type": "string", "nullable": true }, "rarity": { "type": "string", "nullable": true }, "sealed": { "type": "boolean", "nullable": true }, "marketPrice": { "type": "number", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "lowestPriceWithShipping": { "type": "number", "nullable": true }, "totalListings": { "type": "integer", "nullable": true }, "url": { "type": "string", "nullable": true } } }, "otherMatches": { "type": "array", "items": { "type": "object", "nullable": true, "properties": { "productId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "productLine": { "type": "string", "nullable": true }, "setName": { "type": "string", "nullable": true }, "number": { "type": "string", "nullable": true }, "rarity": { "type": "string", "nullable": true }, "sealed": { "type": "boolean", "nullable": true }, "marketPrice": { "type": "number", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "lowestPriceWithShipping": { "type": "number", "nullable": true }, "totalListings": { "type": "integer", "nullable": true }, "url": { "type": "string", "nullable": true } } } }, "salesHistory": { "type": "string", "enum": [ "full", "limited" ] }, "totalSales": { "type": "integer", "nullable": true }, "totalItems": { "type": "integer" }, "items": { "type": "array", "items": { "type": "object", "properties": { "title": { "type": "string", "nullable": true }, "condition": { "type": "string", "nullable": true }, "variant": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "nullable": true }, "price": { "type": "number", "nullable": true }, "shipping": { "type": "number", "nullable": true }, "totalPrice": { "type": "number", "nullable": true }, "soldAt": { "type": "string", "nullable": true }, "listingType": { "type": "string", "nullable": true } } } }, "priceHistory": { "type": "array", "nullable": true, "items": { "type": "object", "properties": { "date": { "type": "string" }, "variant": { "type": "string" }, "condition": { "type": "string" }, "language": { "type": "string" }, "marketPrice": { "type": "number" }, "quantitySold": { "type": "integer" }, "transactionCount": { "type": "integer" }, "lowSalePrice": { "type": "number" }, "highSalePrice": { "type": "number" } } } }, "summary": { "type": "object", "nullable": true }, "scrapedAt": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } } } } }, "/v1/tcgplayer/listings": { "get": { "tags": [ "TCGplayer" ], "summary": "TCGplayer active listings", "description": "Active TCGplayer listings for a product with price, shipping, condition and seller details. One successful call uses one request.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "keyword", "in": "query", "required": false, "schema": { "type": "string", "maxLength": 300, "example": "charizard ex obsidian flames 223", "description": "Card or product name (required unless productId is sent)" } }, { "name": "productId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "description": "Exact TCGplayer product ID" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 1, "description": "Page number" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 50, "default": 25, "description": "Listings per page" } }, { "name": "condition", "in": "query", "required": false, "schema": { "type": "string", "example": "Near Mint", "description": "Condition filter" } }, { "name": "variant", "in": "query", "required": false, "schema": { "type": "string", "example": "Holofoil", "description": "Variant filter" } }, { "name": "language", "in": "query", "required": false, "schema": { "type": "string", "example": "English", "description": "Language filter" } } ], "responses": { "200": { "description": "Listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string" }, "page": { "type": "integer" }, "count": { "type": "integer" }, "marketplace": { "type": "string" }, "product": { "type": "object", "nullable": true, "properties": { "productId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "productLine": { "type": "string", "nullable": true }, "setName": { "type": "string", "nullable": true }, "number": { "type": "string", "nullable": true }, "rarity": { "type": "string", "nullable": true }, "sealed": { "type": "boolean", "nullable": true }, "marketPrice": { "type": "number", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "lowestPriceWithShipping": { "type": "number", "nullable": true }, "totalListings": { "type": "integer", "nullable": true }, "url": { "type": "string", "nullable": true } } }, "otherMatches": { "type": "array", "items": { "type": "object", "nullable": true, "properties": { "productId": { "type": "integer", "nullable": true }, "name": { "type": "string", "nullable": true }, "productLine": { "type": "string", "nullable": true }, "setName": { "type": "string", "nullable": true }, "number": { "type": "string", "nullable": true }, "rarity": { "type": "string", "nullable": true }, "sealed": { "type": "boolean", "nullable": true }, "marketPrice": { "type": "number", "nullable": true }, "lowestPrice": { "type": "number", "nullable": true }, "lowestPriceWithShipping": { "type": "number", "nullable": true }, "totalListings": { "type": "integer", "nullable": true }, "url": { "type": "string", "nullable": true } } } }, "totalListings": { "type": "integer", "nullable": true }, "totalItems": { "type": "integer" }, "hasNextPage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string", "nullable": true }, "price": { "type": "number", "nullable": true }, "shipping": { "type": "number", "nullable": true }, "totalPrice": { "type": "number", "nullable": true }, "condition": { "type": "string", "nullable": true }, "variant": { "type": "string", "nullable": true }, "language": { "type": "string", "nullable": true }, "quantity": { "type": "integer", "nullable": true }, "sellerName": { "type": "string", "nullable": true }, "sellerRating": { "type": "number", "nullable": true }, "sellerSales": { "type": "integer", "nullable": true }, "sellerLocation": { "type": "string", "nullable": true }, "goldSeller": { "type": "boolean", "nullable": true }, "verifiedSeller": { "type": "boolean", "nullable": true }, "directSeller": { "type": "boolean", "nullable": true } } } }, "scrapedAt": { "type": "string" } } } } } }, "400": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "401": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "429": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "502": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } }, "503": { "description": "Error", "content": { "application/json": { "schema": { "type": "object", "properties": { "code": { "type": "string" }, "error": { "type": "string" }, "requestId": { "type": "string" } } } } } } } } }, "/v1/scrape": { "get": { "summary": "Search eBay sold or active listings", "description": "Returns completed eBay sales by default. Set sold=false for current active listings.", "operationId": "searchSoldListings", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Product to search. Supports eBay operators, e.g. minus-sign exclusions ('airpods pro -case')." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 240, "default": 240 }, "description": "Maximum items to return per page. This is a ceiling; fewer valid rows may remain after baseline validation, date filters, or relevance cleanup." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "default": 1 } }, { "name": "ebaySite", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ], "default": "ebay.com" }, "description": "eBay marketplace." }, { "name": "categoryId", "in": "query", "required": false, "schema": { "type": "string", "default": "0" }, "description": "eBay category id (_sacat)." }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "endedRecently", "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest" ] } }, { "name": "itemLocation", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "default", "domestic", "worldwide" ], "default": "default" } }, { "name": "itemCondition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "any", "new", "used" ] } }, { "name": "conditionId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Numeric eBay condition id; overrides itemCondition." }, { "name": "buyingFormat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "auction", "buyItNow", "acceptsOffers" ], "default": "all" } }, { "name": "sellerType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "private", "business" ] }, "description": "Filters labeled sellers on ebay.de, ebay.fr, ebay.it, and ebay.es. Ignored elsewhere; unlabeled EU rows are excluded while filtering." }, { "name": "minPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "includeCompleteListing", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "Sold-search compatibility option. Ignored when sold=false." }, { "name": "sold", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "true returns completed sales. false returns current active listings with currentPrice, watcherCount, unitsSold, acceptsOffers, and timeLeft when visible." }, { "name": "soldAfter", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "soldBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "aspectFilter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON object of human-readable eBay facet names. Values may be strings, pipe-delimited strings, or arrays of strings." }, { "name": "exactMatch", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, removes listings after eBay's explicit Results matching fewer words boundary before relevance cleanup. When the boundary is absent, rows are unchanged. This follows eBay's section split and does not independently prove semantic exactness. false preserves the existing broad-search cache and behavior. Leave it off for long, specific keywords (full card numbers, full set names): eBay often has no exact matches for those, so exactMatch=true can return no results even when the item sold many times." }, { "name": "relevance", "in": "query", "required": false, "schema": { "type": "boolean", "default": true }, "description": "When true, query-aware deterministic checks remove explicit pricing mismatches before one bounded semantic cleanup stage handles accessories, parts, and wrong models. Explicit query intent is preserved. false disables both relevance stages and returns broad valid matches. Baseline validation of item IDs, item URLs, prices, sold dates, and duplicate IDs always applies." }, { "name": "bestOfferPrice", "in": "query", "required": false, "schema": { "type": "boolean", "default": false }, "description": "When true, sold rows where bestOfferAccepted is true gain acceptedOfferPrice (the price the buyer actually paid, null unless found) and acceptedOfferPriceStatus (found, pending or not_available). soldPrice is never changed. US-dollar sales only; other currencies return not_available. No extra charge. Ignored with sold=false." } ], "responses": { "200": { "description": "Sold listings with price intelligence, or active listings with visible demand signals.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } } }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Inspect the response code. Retry rate_limited after Retry-After; never loop on quota_exceeded.", "headers": { "Retry-After": { "description": "Seconds to wait before retrying a rate_limited request. Not used for monthly quota exhaustion.", "schema": { "type": "integer" } }, "X-RateLimit-Limit": { "description": "Maximum requests in the current one-minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Remaining": { "description": "Requests left in the current one-minute window.", "schema": { "type": "integer" } }, "X-RateLimit-Reset": { "description": "Unix timestamp when the current one-minute window resets.", "schema": { "type": "integer" } }, "X-Usage-Limit": { "description": "Monthly request quota.", "schema": { "type": "integer" } }, "X-Usage-Remaining": { "description": "Monthly requests remaining.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "eBay temporarily blocked the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/scrape/category": { "get": { "summary": "Browse eBay sold listings by category", "description": "Returns completed eBay sales from one category without requiring a keyword. Uses the same authentication, quota, filtering, response shape, and error contract as /v1/scrape.", "operationId": "browseSoldListingsByCategory", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "categoryId", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^[1-9][0-9]*$" }, "description": "Positive numeric eBay category id (_sacat)." }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 240, "default": 240 }, "description": "Maximum items to return per page. This is a ceiling; fewer valid rows may remain after baseline validation and filtering." }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "ebaySite", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ], "default": "ebay.com" } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "endedRecently", "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest", "distanceNearest" ] } }, { "name": "itemCondition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "any", "new", "used" ] } }, { "name": "conditionId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "buyingFormat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "auction", "buyItNow", "acceptsOffers" ] } }, { "name": "sellerType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "private", "business" ] }, "description": "EU marketplaces only." }, { "name": "minPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "aspectFilter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON object of human-readable eBay facets." } ], "responses": { "200": { "description": "Category sold listings and price summary. keyword is an empty string.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScrapeResponse" } } } }, "400": { "description": "Missing or invalid categoryId or filters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Per-minute rate limit or monthly quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "eBay temporarily blocked the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Scraping service temporarily at capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/summary": { "get": { "summary": "Get sold-price intelligence without listing rows", "description": "Runs the same sold search and billing flow as /v1/scrape, but returns only the cleaned price summary, raw comparison evidence, result counts, and cache status.", "operationId": "getPriceSummary", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "keyword", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "count", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 240, "default": 240 } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "ebaySite", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ], "default": "ebay.com" } }, { "name": "categoryId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "sortOrder", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "endedRecently", "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest", "distanceNearest" ] } }, { "name": "minPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "maxPrice", "in": "query", "required": false, "schema": { "type": "number" } }, { "name": "itemCondition", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "any", "new", "used" ] } }, { "name": "conditionId", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 } }, { "name": "buyingFormat", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "all", "auction", "buyItNow", "acceptsOffers" ] } }, { "name": "sellerType", "in": "query", "required": false, "schema": { "type": "string", "enum": [ "private", "business" ] } }, { "name": "soldAfter", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "soldBefore", "in": "query", "required": false, "schema": { "type": "string", "format": "date" } }, { "name": "aspectFilter", "in": "query", "required": false, "schema": { "type": "string" }, "description": "JSON object of eBay facet names and values." }, { "name": "exactMatch", "in": "query", "required": false, "schema": { "type": "boolean", "default": false } }, { "name": "relevance", "in": "query", "required": false, "schema": { "type": "boolean", "default": true } } ], "responses": { "200": { "description": "Price summary and raw-versus-cleaned evidence.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SummaryResponse" } } } }, "400": { "description": "Invalid parameters.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks comps:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Rate limit or all available billing sources exhausted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "eBay temporarily blocked the upstream request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Scraping service temporarily at capacity.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/best-offer-prices": { "get": { "summary": "Look up saved accepted Best Offer prices", "description": "Returns the saved accepted Best Offer price for up to 100 eBay item IDs seen in earlier bestOfferPrice=true searches. Free: does not count against monthly requests. Uses the normal per-minute rate limit.", "operationId": "getBestOfferPrices", "parameters": [ { "name": "itemIds", "in": "query", "required": true, "schema": { "type": "string" }, "description": "1 to 100 eBay item IDs, separated by commas." } ], "responses": { "200": { "description": "One entry per item ID with acceptedOfferPrice (string or null) and acceptedOfferPriceStatus (found, pending, not_available or unknown).", "content": { "application/json": { "schema": { "type": "object", "properties": { "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "acceptedOfferPrice": { "type": "string", "nullable": true }, "acceptedOfferPriceStatus": { "type": "string", "enum": ["found", "pending", "not_available", "unknown"] } } } }, "requestId": { "type": "string" } } } } } }, "400": { "description": "itemIds missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/account/usage": { "get": { "summary": "Get account quota and purchased-credit usage", "description": "Returns the authenticated account's monthly allowance, current usage, billing period, rate limit, purchased-credit balance, and total available requests.", "operationId": "getAccountUsage", "responses": { "200": { "description": "Current account usage and credit balance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccountUsageResponse" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks account:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/bulk-search": { "post": { "summary": "Stream multiple keyword searches", "description": "Search up to 20 unique keywords with at most three concurrent workers. If only part of the input fits the selected billing balance, the first keywords run and the remainder receive per-keyword quota_exceeded result events. Each successful keyword consumes one request; failures do not. Results stream as Server-Sent Events and may complete out of order.", "operationId": "bulkSearch", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Replay a completed run with the identical request body without repeating searches or consuming quota." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkSearchRequest" } } } }, "responses": { "200": { "description": "SSE stream containing start, result, and complete events.", "content": { "text/event-stream": { "schema": { "type": "string", "description": "Each data field contains one JSON event payload." } } } }, "400": { "description": "Invalid keywords or shared options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks comps:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The idempotency key has another body, or a bulk run is already active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "No keyword can be allocated because the selected monthly and credit balance is empty.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/bulk-search/{runId}/download.csv": { "get": { "summary": "Download bulk-search CSV", "description": "Download every successful keyword in one CSV, or pass index for one submitted keyword. Requires the same account's bearer credential.", "operationId": "downloadBulkSearchCsv", "parameters": [ { "name": "runId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "index", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Original zero-based keyword index. Omit for a combined CSV." } ], "responses": { "200": { "description": "CSV export.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Invalid runId or index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Run or requested successful keyword not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "The run is still active.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/cards/batch": { "post": { "summary": "Submit a sports or trading-card comps batch", "description": "Submit up to 100 cards in one HTTP request. Cards are processed asynchronously and sequentially. Each successfully processed card consumes one normal monthly request.", "operationId": "submitCardBatch", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Safely retry a submission without creating a duplicate job." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBatchRequest" } } } }, "responses": { "202": { "description": "Batch accepted.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBatchAccepted" } } } }, "400": { "description": "Invalid card batch.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Another card batch is already active for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Submission rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/cards/batch/{jobId}": { "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "summary": "Get card batch progress and results", "operationId": "getCardBatch", "responses": { "200": { "description": "Current progress, including completed per-card results.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CardBatchJob" } } } }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } }, "delete": { "summary": "Cancel a queued or running card batch", "operationId": "cancelCardBatch", "responses": { "200": { "description": "Cancellation requested or existing terminal status returned." }, "404": { "description": "Batch not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/scrape/max": { "post": { "summary": "Start an asynchronous Max Mode search", "description": "Searches up to 100 eBay result pages in the background. Each successful page uses one monthly request, then one purchased credit after monthly quota is exhausted.", "operationId": "startMaxSearch", "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "maxLength": 200 }, "description": "Return the previously created job when a submission is retried." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxSearchRequest" } } } }, "responses": { "200": { "description": "Existing idempotent job returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxJobAccepted" } } } }, "202": { "description": "Max Mode job queued.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxJobAccepted" } } } }, "400": { "description": "Invalid request body or search options.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks jobs:write scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Another Max Mode job is active for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Submission rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/scrape/max/results/{jobId}": { "get": { "summary": "Poll Max Mode progress or results", "operationId": "getMaxSearchResults", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Current job progress or terminal result.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxJob" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks comps:read scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Job not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/scrape/max/{jobId}": { "delete": { "summary": "Cancel a queued or running Max Mode job", "operationId": "cancelMaxSearch", "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "responses": { "200": { "description": "Cancellation requested or existing terminal status returned.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MaxCancelResponse" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks jobs:write scope.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "404": { "description": "Job not found for this account.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/scrape/max/{jobId}/download.csv": { "get": { "summary": "Download a signed Max Mode CSV", "description": "Downloads the stored job result using the signed token returned for download or email delivery. The token itself authorizes this URL.", "operationId": "downloadMaxSearchCsv", "security": [], "parameters": [ { "name": "jobId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "CSV export.", "content": { "text/csv": { "schema": { "type": "string" } } } }, "403": { "description": "Invalid or expired signed token." }, "404": { "description": "Job not found." } } } }, "/v1/poshmark/sold": { "get": { "tags": [ "Poshmark" ], "summary": "Scrape Poshmark sold listings", "description": "Returns one native page of public Poshmark sold listings. Authentication, rate limits, monthly quota, purchased credits, request IDs, and cache headers match the other CompSniper endpoints. Each successful page uses one CompSniper request, including enrich=true. The native page ceiling is 48 listings.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "schema": { "type": "string", "minLength": 1, "description": "Poshmark search term", "example": "louis vuitton neverfull" }, "required": true, "name": "keyword", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number. Each page returns up to 48 items.", "example": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "description": "Minimum price filter (USD)", "example": 50 }, "required": false, "name": "minPrice", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "description": "Maximum price filter (USD)", "example": 500 }, "required": false, "name": "maxPrice", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "women", "men", "kids", "home", "pets", "electronics" ], "default": "all", "description": "Poshmark department filter" }, "required": false, "name": "department", "in": "query" }, { "schema": { "type": "string", "enum": [ "all", "nwt" ], "default": "all", "description": "Condition filter. 'nwt' = New With Tags only." }, "required": false, "name": "condition", "in": "query" }, { "schema": { "type": "string", "description": "Filter by brand name", "example": "Louis Vuitton" }, "required": false, "name": "brand", "in": "query" }, { "schema": { "type": "string", "enum": [ "sold_recently", "price_asc", "price_desc", "likes" ], "default": "sold_recently", "description": "Sort order for results" }, "required": false, "name": "sortBy", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "Adds public seller location, approximate sold-count evidence, and average ship time. Sold date, listed date, colors, description, category, and condition are already returned when present in the native search response. This still uses one CompSniper request.", "example": "false" }, "required": false, "name": "enrich", "in": "query", "description": "Adds public seller location, approximate sold-count evidence, and average ship time. Sold date, listed date, colors, description, category, and condition are already returned when present in the native search response. This still uses one CompSniper request." } ], "responses": { "200": { "description": "Sold listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string" }, "page": { "type": "number", "description": "Current page number" }, "totalItems": { "type": "number", "description": "Number of items returned in this response (up to 48)" }, "hasNextPage": { "type": "boolean", "description": "Whether more pages of results are available." }, "items": { "type": "array", "items": { "type": "object", "properties": { "listingId": { "type": "string", "description": "Poshmark listing ID (24-char hex)", "example": "6478a1b2c3d4e5f6a7b8c9d0" }, "url": { "type": "string", "example": "https://poshmark.com/listing/Louis-Vuitton-Neverfull-6478a1b2c3d4e5f6a7b8c9d0" }, "title": { "type": "string", "example": "Louis Vuitton Neverfull MM Damier Ebene" }, "soldPrice": { "type": "number", "nullable": true, "description": "Sale price in USD", "example": 1250 }, "originalPrice": { "type": "number", "nullable": true, "description": "Original listing price in USD", "example": 1960 }, "shippingCost": { "type": "number", "nullable": true, "description": "Reserved for item-level shipping evidence. null when Poshmark does not expose it.", "example": 7.97 }, "brand": { "type": "string", "nullable": true, "example": "Louis Vuitton" }, "size": { "type": "string", "nullable": true, "example": "OS" }, "category": { "type": "string", "nullable": true, "description": "Department > Category path.", "example": "Women > Bags > Totes" }, "condition": { "type": "string", "nullable": true, "description": "Item condition from Poshmark API.", "example": "Pre-owned" }, "nwt": { "type": "boolean", "description": "New With Tags flag" }, "colors": { "type": "array", "items": { "type": "string" }, "description": "Color names from Poshmark API.", "example": [ "Brown" ] }, "description": { "type": "string", "nullable": true, "description": "Full listing description text." }, "soldAt": { "type": "string", "nullable": true, "description": "Public ISO timestamp when Poshmark marked the item sold.", "example": "2026-07-15T18:30:00.000Z" }, "listedAt": { "type": "string", "nullable": true, "description": "ISO timestamp when the item was first published.", "example": "2026-06-01T12:00:00.000Z" }, "daysToSell": { "type": "number", "nullable": true, "description": "Days between listedAt and soldAt. null when either date is missing.", "example": 44.27 }, "likesCount": { "type": "number", "nullable": true, "example": 23 }, "commentsCount": { "type": "number", "nullable": true, "description": "Public comment count when exposed by Poshmark search.", "example": 4 }, "shareCount": { "type": "number", "nullable": true, "description": "Public share count when exposed by Poshmark search.", "example": 12 }, "sellerUsername": { "type": "string", "nullable": true, "example": "luxurycloset" }, "sellerLocation": { "type": "string", "nullable": true, "description": "Seller city + state. Requires enrich=true.", "example": "Los Angeles, CA" }, "sellerSoldCount": { "type": "number", "nullable": true, "description": "Approximate public seller sold count. Requires enrich=true.", "example": 847 }, "sellerAvgShipTime": { "type": "number", "nullable": true, "description": "Seller's average ship time in days. Requires enrich=true.", "example": 1.5 }, "thumbnailUrl": { "type": "string", "nullable": true, "description": "Listing thumbnail URL", "example": "https://di2ponv0v5otw.cloudfront.net/posts/2026/07/15/..." }, "scrapedAt": { "type": "string", "description": "ISO timestamp when the listing was scraped", "example": "2026-08-08T14:30:00.000Z" } }, "required": [ "listingId", "url", "title", "soldPrice", "originalPrice", "shippingCost", "brand", "size", "category", "condition", "nwt", "colors", "description", "soldAt", "listedAt", "daysToSell", "likesCount", "commentsCount", "shareCount", "sellerUsername", "sellerLocation", "sellerSoldCount", "sellerAvgShipTime", "thumbnailUrl", "scrapedAt" ] } }, "summary": { "allOf": [ { "$ref": "#/components/schemas/PriceSummary" } ], "nullable": true } }, "required": [ "keyword", "page", "totalItems", "hasNextPage", "items", "summary" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "error": { "type": "string" }, "plan": { "type": "string" }, "limit": { "type": "number" }, "remaining": { "type": "number", "enum": [ 0 ] }, "retry_after": { "type": "number" }, "reset": { "type": "number" } }, "required": [ "code", "error", "plan", "limit", "remaining", "retry_after", "reset" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "error": { "type": "string" }, "plan": { "type": "string" }, "limit": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number", "enum": [ 0 ] }, "reset_at": { "type": "string" }, "retry_after": { "type": "number" }, "upgrade_url": { "type": "string" } }, "required": [ "code", "error", "plan", "limit", "used", "remaining", "reset_at", "retry_after", "upgrade_url" ] } ] } } } }, "500": { "description": "Scrape failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "Poshmark fetch failed after retry", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Server busy: concurrency limit reached; retry shortly", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } } }, "operationId": "searchPoshmarkSold" } }, "/v1/mercari": { "get": { "tags": [ "Mercari" ], "summary": "Search Mercari sold or active listings", "description": "Returns one page of public Mercari sold or active listings through a managed anonymous guest session. Authentication, rate limits, monthly quota, purchased credits, request IDs, and cache headers match the other CompSniper endpoints. Each successful page uses one CompSniper request and returns up to 100 items.", "security": [ { "bearerAuth": [] } ], "parameters": [ { "$ref": "#/components/parameters/CreditSource" }, { "schema": { "type": "string", "minLength": 1, "description": "Mercari search term", "example": "pokemon cards" }, "required": true, "name": "keyword", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "default": 1, "description": "Page number, maps to offset = (page - 1) * count", "example": 1 }, "required": false, "name": "page", "in": "query" }, { "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100, "description": "Items per page (max 100)", "example": 100 }, "required": false, "name": "count", "in": "query" }, { "schema": { "type": "string", "enum": [ "bestMatch", "newest", "lowestPrice", "highestPrice", "recentlySold", "mostPopular" ], "default": "bestMatch", "description": "Sort order. recentlySold maps to Mercari's current Recently sold option. mostPopular is accepted as a compatibility alias for recentlySold." }, "required": false, "name": "sortOrder", "in": "query", "description": "Sort order. recentlySold maps to Mercari's current Recently sold option. mostPopular is accepted as a compatibility alias for recentlySold." }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "description": "Minimum price filter in dollars", "example": 10 }, "required": false, "name": "minPrice", "in": "query" }, { "schema": { "type": "number", "nullable": true, "minimum": 0, "description": "Maximum price filter in dollars", "example": 100 }, "required": false, "name": "maxPrice", "in": "query" }, { "schema": { "type": "string", "enum": [ "any", "new", "likeNew", "good", "fair", "poor" ], "default": "any", "description": "Condition filter" }, "required": false, "name": "itemCondition", "in": "query" }, { "schema": { "type": "string", "description": "Mercari category ID" }, "required": false, "name": "categoryId", "in": "query" }, { "schema": { "type": "string", "description": "Mercari brand ID" }, "required": false, "name": "brandId", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "true", "description": "true = sold listings (default), false = active listings", "example": "true" }, "required": false, "name": "sold", "in": "query" }, { "schema": { "type": "string", "enum": [ "true", "false" ], "default": "false", "description": "true = add listedAt (the date Mercari shows as \"Posted\", ISO 8601 UTC) to each result. Slower: each listing is looked up separately. null when a date cannot be read.", "example": "true" }, "required": false, "name": "includeListedAt", "in": "query" } ], "responses": { "200": { "description": "Mercari listings", "content": { "application/json": { "schema": { "type": "object", "properties": { "keyword": { "type": "string" }, "page": { "type": "number" }, "count": { "type": "number" }, "totalResults": { "type": "number" }, "totalItems": { "type": "number" }, "hasNextPage": { "type": "boolean" }, "items": { "type": "array", "items": { "type": "object", "properties": { "itemId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "price": { "type": "string", "description": "Dollars, 2 decimal places", "example": "25.00" }, "currency": { "type": "string", "enum": [ "USD" ] }, "originalPrice": { "type": "string", "nullable": true }, "condition": { "type": "string", "nullable": true }, "conditionId": { "type": "number", "nullable": true }, "status": { "type": "string", "enum": [ "sold", "active" ] }, "imageUrl": { "type": "string", "nullable": true }, "thumbnailUrl": { "type": "string", "nullable": true }, "sellerId": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "nullable": true }, "brand": { "type": "string", "nullable": true }, "categoryId": { "type": "number", "nullable": true }, "categoryName": { "type": "string", "nullable": true }, "marketplace": { "type": "string", "enum": [ "mercari" ] } }, "required": [ "itemId", "url", "title", "price", "currency", "originalPrice", "condition", "conditionId", "status", "imageUrl", "thumbnailUrl", "sellerId", "brand", "categoryId", "categoryName", "marketplace" ] } }, "marketplace": { "type": "string", "enum": [ "mercari" ] }, "scrapedAt": { "type": "string" }, "summary": { "allOf": [ { "$ref": "#/components/schemas/PriceSummary" } ], "nullable": true } }, "required": [ "keyword", "page", "count", "totalResults", "totalItems", "hasNextPage", "items", "marketplace", "scrapedAt", "summary" ] } } } }, "400": { "description": "Invalid query parameters", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "401": { "description": "Missing or invalid API key", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" } }, "required": [ "error" ] } } } }, "429": { "description": "Rate limit or quota exceeded", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "code": { "type": "string", "enum": [ "rate_limited" ] }, "error": { "type": "string" }, "plan": { "type": "string" }, "limit": { "type": "number" }, "remaining": { "type": "number", "enum": [ 0 ] }, "retry_after": { "type": "number" }, "reset": { "type": "number" } }, "required": [ "code", "error", "plan", "limit", "remaining", "retry_after", "reset" ] }, { "type": "object", "properties": { "code": { "type": "string", "enum": [ "quota_exceeded" ] }, "error": { "type": "string" }, "plan": { "type": "string" }, "limit": { "type": "number" }, "used": { "type": "number" }, "remaining": { "type": "number", "enum": [ 0 ] }, "reset_at": { "type": "string" }, "retry_after": { "type": "number" }, "upgrade_url": { "type": "string" } }, "required": [ "code", "error", "plan", "limit", "used", "remaining", "reset_at", "retry_after", "upgrade_url" ] } ] } } } }, "500": { "description": "Search failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "502": { "description": "mercari-api fetch failed", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" } }, "required": [ "error" ] } } } }, "503": { "description": "Temporary Mercari connection failure (upstream_unavailable) or exhausted search capacity (server_busy). Failed requests do not consume allowance. Retry after the Retry-After delay.", "headers": { "Retry-After": { "schema": { "type": "integer" }, "description": "Seconds to wait before retrying." }, "X-Request-ID": { "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } }, "operationId": "searchMercariListings" } }, "/v1/shipping/rates": { "post": { "tags": [ "Shipping Rates" ], "summary": "Get eBay shipping-rate estimates", "description": "Returns quote-only shipping estimates for a US origin ZIP, US destination ZIP, package weight, and dimensions. Applicable services are returned in rates. Carrier-packaging and content-restricted services are returned in conditionalRates unless the caller explicitly confirms the requirement. Preserves retail and eBay discounted prices when available. Requires a separate Shipping Rates subscription and consumes one shipping request only when usable applicable rates are returned.", "operationId": "getShippingRates", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "minLength": 1, "maxLength": 128, "pattern": "^[!-~]+$" }, "description": "Replays a completed identical quote without consuming another shipping request. Use a new key for a different request body." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateRequest" } } } }, "responses": { "200": { "description": "Usable shipping-rate estimates. One separate shipping request is consumed unless this is an idempotent replay.", "headers": { "X-Shipping-Plan": { "schema": { "type": "string" } }, "X-Shipping-Usage-Limit": { "schema": { "type": "integer" } }, "X-Shipping-Usage-Used": { "schema": { "type": "integer" } }, "X-Shipping-Usage-Remaining": { "schema": { "type": "integer" } }, "X-Shipping-Usage-Reset": { "schema": { "type": "string", "format": "date-time" } }, "X-Idempotent-Replay": { "schema": { "type": "boolean" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateResponse" } } } }, "400": { "description": "Malformed JSON or invalid route or package details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks access or the account has no active Shipping Rates subscription.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "409": { "description": "Idempotency key conflict or an identical request with that key is still running.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "413": { "description": "Request body exceeds 16 KB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "422": { "description": "No shipping services were available. No shipping request is consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "429": { "description": "Shipping rate limit or independent monthly shipping quota exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "502": { "description": "Shipping-rate source is temporarily unavailable. No shipping request is consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "503": { "description": "Shipping-rate capacity is temporarily busy. No shipping request is consumed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } }, "/v1/shipping/usage": { "get": { "tags": [ "Shipping Rates" ], "summary": "Get Shipping Rates usage", "description": "Returns the authenticated account's separate Shipping Rates plan, quota, usage, rate limit, and billing period.", "operationId": "getShippingRateUsage", "responses": { "200": { "description": "Current independent Shipping Rates entitlement and usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShippingRateUsageResponse" } } } }, "401": { "description": "Missing or invalid API key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } }, "403": { "description": "Credential lacks access to account usage.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiError" } } } } } } } }, "components": { "parameters": { "CreditSource": { "name": "X-Credit-Source", "in": "header", "required": false, "schema": { "type": "string", "enum": [ "credits" ] }, "description": "Omit to use temporary carryover first, then monthly quota, then purchased credits. Set to credits to spend a purchased credit directly. Failed searches are not charged." } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Send your API key as 'Authorization: Bearer cs_live_...'." } }, "schemas": { "ScrapeResponse": { "type": "object", "properties": { "keyword": { "type": "string" }, "page": { "type": "integer" }, "totalItems": { "type": "integer", "description": "Valid items on this page after baseline validation and filtering." }, "totalResults": { "type": "string", "nullable": true, "description": "eBay's own reported total, e.g. '7,900'." }, "hasNextPage": { "type": "boolean" }, "summary": { "$ref": "#/components/schemas/PriceSummary", "description": "Sold-price intelligence. null for active searches." }, "items": { "type": "array", "items": { "oneOf": [ { "$ref": "#/components/schemas/SoldItem" }, { "$ref": "#/components/schemas/ActiveItem" } ] } } } }, "PriceSummary": { "type": "object", "nullable": true, "description": "Deterministic price intelligence over the returned sold items.", "properties": { "count": { "type": "integer", "description": "Items with a usable sold price." }, "currency": { "type": "string", "nullable": true }, "median": { "type": "number" }, "mean": { "type": "number" }, "min": { "type": "number" }, "max": { "type": "number" }, "p25": { "type": "number", "description": "Lower bound of the realistic range." }, "p75": { "type": "number", "description": "Upper bound of the realistic range." }, "avgShipping": { "type": "number", "nullable": true } } }, "SummaryResponse": { "type": "object", "required": [ "keyword", "totalItems", "cached" ], "properties": { "keyword": { "type": "string" }, "totalResults": { "type": "string", "nullable": true }, "totalItems": { "type": "integer" }, "rawMedian": { "type": "number", "nullable": true }, "rawSampleCount": { "type": "integer", "nullable": true }, "summary": { "$ref": "#/components/schemas/PriceSummary" }, "cached": { "type": "boolean" } } }, "AccountUsageResponse": { "type": "object", "required": [ "plan", "quota", "used", "remaining", "periodStart", "rateLimitPerMinute", "sharedFreeQuota", "rolloverBalance", "creditBalance", "totalAvailable", "purchaseCreditsUrl" ], "properties": { "plan": { "type": "string" }, "quota": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time", "nullable": true }, "rateLimitPerMinute": { "type": "integer" }, "sharedFreeQuota": { "type": "boolean" }, "rolloverBalance": { "type": "integer", "description": "Unused monthly requests carried from a full-price upgrade. These expire at the next renewal." }, "creditBalance": { "type": "integer" }, "totalAvailable": { "type": "integer", "description": "Carryover plus monthly requests remaining plus purchased credits." }, "purchaseCreditsUrl": { "type": "string", "format": "uri" } } }, "ShippingRateRequest": { "type": "object", "additionalProperties": false, "required": [ "shipFrom", "shipTo", "package" ], "properties": { "ebaySite": { "type": "string", "enum": ["ebay.com"], "default": "ebay.com" }, "shipFrom": { "type": "object", "additionalProperties": false, "required": ["postalCode"], "properties": { "countryCode": { "type": "string", "enum": ["US"], "default": "US" }, "postalCode": { "type": "string", "pattern": "^[0-9]{5}(-[0-9]{4})?$", "example": "10001" } } }, "shipTo": { "type": "object", "additionalProperties": false, "required": ["postalCode"], "properties": { "countryCode": { "type": "string", "enum": ["US"], "default": "US" }, "postalCode": { "type": "string", "pattern": "^[0-9]{5}(-[0-9]{4})?$", "example": "90210" } } }, "package": { "type": "object", "additionalProperties": false, "required": ["weight", "dimensions"], "properties": { "type": { "type": "string", "default": "custom", "enum": [ "custom", "usps_flat_rate_envelope", "usps_padded_flat_rate_envelope", "usps_legal_flat_rate_envelope", "usps_small_flat_rate_box", "usps_medium_flat_rate_box", "usps_large_flat_rate_box", "usps_express_flat_rate_envelope", "fedex_one_rate_envelope", "fedex_one_rate_pak", "fedex_one_rate_extra_small_box", "fedex_one_rate_small_box", "fedex_one_rate_medium_box", "fedex_one_rate_large_box", "fedex_one_rate_extra_large_box", "fedex_one_rate_tube" ], "description": "Select custom unless the shipment will use the exact named carrier packaging." }, "weight": { "oneOf": [ { "type": "object", "additionalProperties": false, "required": ["value", "unit"], "properties": { "value": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 150, "example": 2 }, "unit": { "type": "string", "enum": ["lb"] } } }, { "type": "object", "additionalProperties": false, "required": ["value", "unit"], "properties": { "value": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 2400, "example": 32 }, "unit": { "type": "string", "enum": ["oz"] } } } ] }, "dimensions": { "type": "object", "additionalProperties": false, "required": ["length", "width", "height", "unit"], "properties": { "length": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 120, "example": 10 }, "width": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 120, "example": 8 }, "height": { "type": "number", "exclusiveMinimum": true, "minimum": 0, "maximum": 120, "example": 4 }, "unit": { "type": "string", "enum": ["in"] } } }, "irregular": { "type": "boolean", "default": false } } }, "contents": { "type": "object", "additionalProperties": false, "properties": { "mediaMailEligible": { "type": "boolean", "default": false, "description": "Set true only when the contents qualify under USPS Media Mail standards." } } } } }, "ShippingPrice": { "type": "object", "required": ["min", "max", "currency"], "properties": { "min": { "type": "string", "example": "10.05" }, "max": { "type": "string", "nullable": true, "example": null }, "currency": { "type": "string", "example": "USD" } } }, "ShippingRate": { "type": "object", "required": [ "carrierCode", "serviceName", "serviceCode", "serviceGroup", "tracking", "estimatedDeliveryMinHours", "estimatedDeliveryMaxHours", "includedCoverage", "fastest", "discountedPrice", "retailPrice", "effectivePrice", "priceSource", "savingsPercent", "eligibility" ], "properties": { "carrierCode": { "type": "string", "example": "USPS" }, "serviceName": { "type": "string", "example": "USPS Ground Advantage" }, "serviceCode": { "type": "string", "example": "USPSParcel" }, "serviceGroup": { "type": "string", "nullable": true }, "tracking": { "type": "boolean" }, "estimatedDeliveryMinHours": { "type": "integer", "nullable": true }, "estimatedDeliveryMaxHours": { "type": "integer", "nullable": true }, "includedCoverage": { "type": "string", "nullable": true }, "fastest": { "type": "boolean", "description": "True when this applicable service has the shortest maximum delivery window. Ties are allowed." }, "discountedPrice": { "type": "object", "allOf": [{ "$ref": "#/components/schemas/ShippingPrice" }], "nullable": true }, "retailPrice": { "$ref": "#/components/schemas/ShippingPrice" }, "effectivePrice": { "$ref": "#/components/schemas/ShippingPrice" }, "priceSource": { "type": "string", "enum": ["ebay_discounted", "retail"] }, "savingsPercent": { "type": "integer", "nullable": true, "minimum": 0 }, "eligibility": { "type": "object", "required": ["status", "requirements"], "properties": { "status": { "type": "string", "enum": ["eligible", "conditional"] }, "requirements": { "type": "array", "items": { "type": "object", "required": ["type", "code", "message"], "properties": { "type": { "type": "string", "enum": ["carrier_packaging", "eligible_contents"] }, "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "ShippingRateResponse": { "type": "object", "required": ["source", "rateType", "currency", "totalRates", "totalConditionalRates", "fetchedAt", "validUntil", "requestId", "rates", "conditionalRates"], "properties": { "source": { "type": "string", "enum": ["ebay_shipping_calculator"] }, "rateType": { "type": "string", "enum": ["estimate"] }, "currency": { "type": "string", "example": "USD" }, "totalRates": { "type": "integer", "minimum": 1, "description": "Services currently applicable to the submitted package and content declarations." }, "totalConditionalRates": { "type": "integer", "minimum": 0, "description": "Additional services requiring specific carrier packaging or eligible contents." }, "fetchedAt": { "type": "string", "format": "date-time" }, "validUntil": { "type": "string", "format": "date-time" }, "requestId": { "type": "string", "format": "uuid" }, "rates": { "type": "array", "minItems": 1, "items": { "$ref": "#/components/schemas/ShippingRate" } }, "conditionalRates": { "type": "array", "items": { "$ref": "#/components/schemas/ShippingRate" } } } }, "ShippingRateUsageResponse": { "type": "object", "required": ["plan", "status", "quota", "used", "remaining", "rateLimitPerMinute", "subscriptionUrl"], "properties": { "plan": { "type": "string", "example": "shipping-10k" }, "status": { "type": "string", "example": "active" }, "quota": { "type": "integer", "minimum": 0 }, "used": { "type": "integer", "minimum": 0 }, "remaining": { "type": "integer", "minimum": 0 }, "rateLimitPerMinute": { "type": "integer", "minimum": 0 }, "periodStart": { "type": "string", "format": "date-time" }, "periodEnd": { "type": "string", "format": "date-time" }, "subscriptionUrl": { "type": "string", "format": "uri" } } }, "MaxSearchRequest": { "type": "object", "required": [ "keyword" ], "properties": { "keyword": { "type": "string", "maxLength": 300 }, "maxPages": { "type": "integer", "minimum": 1, "maximum": 100, "default": 10 }, "delivery": { "type": "string", "enum": [ "inline", "email", "download" ], "default": "inline" }, "count": { "type": "integer", "minimum": 1, "maximum": 240, "default": 240 }, "ebaySite": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ], "default": "ebay.com" }, "categoryId": { "type": "string" }, "sortOrder": { "type": "string", "enum": [ "endedRecently", "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest", "distanceNearest" ] }, "minPrice": { "type": "number" }, "maxPrice": { "type": "number" }, "itemCondition": { "type": "string", "enum": [ "any", "new", "used" ] }, "conditionId": { "type": "integer", "minimum": 0 }, "sellerType": { "type": "string", "enum": [ "private", "business" ] }, "sold": { "type": "boolean", "default": true }, "exactMatch": { "type": "boolean", "default": false }, "aspectFilter": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } }, "additionalProperties": false }, "MaxJobAccepted": { "type": "object", "required": [ "jobId", "status", "resultsUrl" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "keyword": { "type": "string" }, "maxPages": { "type": "integer" }, "delivery": { "type": "string", "enum": [ "inline", "email", "download" ] }, "resultsUrl": { "type": "string" } } }, "MaxJob": { "type": "object", "required": [ "jobId", "status", "keyword", "maxPages", "pagesDone", "itemsFound", "createdAt", "updatedAt", "creditPreference", "rolloverBalance", "creditBalance" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "maxPages_reached", "cancelled", "failed" ] }, "keyword": { "type": "string" }, "maxPages": { "type": "integer" }, "pagesDone": { "type": "integer" }, "itemsFound": { "type": "integer" }, "totalResults": { "type": "string", "nullable": true }, "createdAt": { "type": "string", "format": "date-time" }, "startedAt": { "type": "string", "format": "date-time", "nullable": true }, "completedAt": { "type": "string", "format": "date-time", "nullable": true }, "updatedAt": { "type": "string", "format": "date-time" }, "progress": { "$ref": "#/components/schemas/MaxProgress" }, "terminationReason": { "type": "string", "enum": [ "natural_end", "maxPages_reached", "quota_exhausted", "upstream_unhealthy", "cancelled", "terminal_error" ], "nullable": true }, "creditPreference": { "type": "string", "enum": [ "auto", "credits" ] }, "rolloverBalance": { "type": "integer", "description": "Temporary carried-over requests remaining." }, "creditBalance": { "type": "integer" }, "resultsUrl": { "type": "string" }, "error": { "type": "string", "nullable": true }, "summary": { "$ref": "#/components/schemas/MaxSummary" }, "delivery": { "type": "object", "properties": { "mode": { "type": "string", "enum": [ "inline", "email", "download" ] }, "status": { "type": "string" }, "downloadUrl": { "type": "string" } } }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/SoldItem" } }, "expiresAt": { "type": "string", "format": "date-time" }, "purchaseCreditsUrl": { "type": "string", "format": "uri" }, "upgradeUrl": { "type": "string", "format": "uri" } } }, "MaxFailedPage": { "type": "object", "required": [ "page", "code", "attempts" ], "properties": { "page": { "type": "integer", "minimum": 1 }, "code": { "type": "string", "enum": [ "upstream_blocked", "engine_error" ] }, "attempts": { "type": "integer", "minimum": 1, "maximum": 2 } } }, "MaxProgress": { "type": "object", "required": [ "currentPage", "pagesAttempted", "pagesSucceeded", "pagesFailed", "failedPages", "itemsCollected", "consecutiveFailures" ], "properties": { "currentPage": { "type": "integer", "minimum": 0 }, "pagesAttempted": { "type": "integer", "minimum": 0 }, "pagesSucceeded": { "type": "integer", "minimum": 0 }, "pagesFailed": { "type": "integer", "minimum": 0 }, "failedPages": { "type": "array", "items": { "$ref": "#/components/schemas/MaxFailedPage" } }, "itemsCollected": { "type": "integer", "minimum": 0 }, "consecutiveFailures": { "type": "integer", "minimum": 0, "maximum": 5 } } }, "MaxSummary": { "type": "object", "required": [ "pagesAttempted", "pagesSucceeded", "pagesFailed", "failedPages", "totalItems", "partial", "terminationReason" ], "properties": { "pagesAttempted": { "type": "integer", "minimum": 0 }, "pagesSucceeded": { "type": "integer", "minimum": 0 }, "pagesFailed": { "type": "integer", "minimum": 0 }, "failedPages": { "type": "array", "items": { "$ref": "#/components/schemas/MaxFailedPage" } }, "totalItems": { "type": "integer", "minimum": 0 }, "partial": { "type": "boolean" }, "terminationReason": { "type": "string", "enum": [ "natural_end", "maxPages_reached", "quota_exhausted", "upstream_unhealthy", "cancelled", "terminal_error" ], "nullable": true } } }, "MaxCancelResponse": { "type": "object", "required": [ "jobId", "status", "cancelRequested" ], "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string" }, "cancelRequested": { "type": "boolean" } } }, "SoldItem": { "type": "object", "properties": { "itemId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "condition": { "type": "string", "nullable": true }, "conditionId": { "type": "integer", "nullable": true, "description": "Best-effort mapping of a known localized eBay condition label." }, "sellerType": { "type": "string", "enum": [ "private", "business" ], "nullable": true, "description": "Labeled seller classification on EU marketplaces." }, "listingType": { "type": "string", "enum": [ "sold" ] }, "bestOfferAccepted": { "type": "boolean", "nullable": true, "description": "true when eBay marked an accepted Best Offer; null when no accepted-offer marker was detected. eBay does not disclose the accepted amount." }, "soldPrice": { "type": "string", "description": "Decimal string." }, "soldCurrency": { "type": "string", "description": "ISO 4217." }, "shippingPrice": { "type": "string", "nullable": true }, "shippingType": { "type": "string", "enum": [ "free", "paid", "pickup", "unknown" ], "nullable": true }, "totalPrice": { "type": "string", "nullable": true }, "endedAt": { "type": "string", "description": "YYYY-MM-DD sold date." }, "sellerUsername": { "type": "string", "nullable": true }, "sellerFeedbackScore": { "type": "integer", "nullable": true }, "productRating": { "type": "number", "minimum": 0, "maximum": 5, "nullable": true, "description": "eBay catalog star rating shown on the result card. This describes the product, not the seller." }, "productReviewCount": { "type": "integer", "minimum": 0, "nullable": true, "description": "Number of eBay catalog ratings behind productRating." }, "itemLocation": { "type": "string", "nullable": true } } }, "ActiveItem": { "type": "object", "description": "A current eBay listing returned when sold=false. Demand fields are null when eBay does not show them on the search card.", "properties": { "itemId": { "type": "string" }, "url": { "type": "string" }, "title": { "type": "string" }, "condition": { "type": "string", "nullable": true }, "conditionId": { "type": "integer", "nullable": true }, "sellerType": { "type": "string", "enum": [ "private", "business" ], "nullable": true }, "listingType": { "type": "string", "enum": [ "active" ] }, "buyingFormat": { "type": "string", "enum": [ "auction", "buyItNow", "auctionWithBIN" ], "nullable": true }, "bidCount": { "type": "integer", "nullable": true }, "currentPrice": { "type": "string", "description": "Current asking or bid price as a decimal string." }, "currentPriceMax": { "type": "string", "nullable": true, "description": "Upper bound when eBay displays a price range." }, "currentCurrency": { "type": "string", "description": "ISO 4217." }, "watcherCount": { "type": "integer", "nullable": true }, "unitsSold": { "type": "integer", "nullable": true }, "acceptsOffers": { "type": "boolean" }, "timeLeft": { "type": "string", "nullable": true, "description": "Raw localized time remaining when visible." }, "shippingPrice": { "type": "string", "nullable": true }, "shippingType": { "type": "string", "enum": [ "free", "paid", "pickup", "unknown" ] }, "totalPrice": { "type": "string", "nullable": true }, "sellerUsername": { "type": "string", "nullable": true }, "sellerFeedbackScore": { "type": "integer", "nullable": true }, "productRating": { "type": "number", "minimum": 0, "maximum": 5, "nullable": true, "description": "eBay catalog star rating shown on the result card. This describes the product, not the seller." }, "productReviewCount": { "type": "integer", "minimum": 0, "nullable": true, "description": "Number of eBay catalog ratings behind productRating." }, "itemLocation": { "type": "string", "nullable": true } } }, "BulkSearchRequest": { "type": "object", "required": [ "keywords" ], "properties": { "keywords": { "type": "array", "minItems": 1, "maxItems": 20, "description": "Case-insensitively deduplicated product keywords. Each keyword may contain at most 300 characters.", "items": { "type": "string", "maxLength": 300 } }, "options": { "$ref": "#/components/schemas/BulkSearchOptions" } } }, "BulkSearchOptions": { "type": "object", "description": "Shared page-one options applied independently to every keyword.", "properties": { "count": { "type": "integer", "minimum": 1, "maximum": 240, "default": 240 }, "ebaySite": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ] }, "categoryId": { "type": "string" }, "sortOrder": { "type": "string", "enum": [ "endedRecently", "timeNewlyListed", "pricePlusPostageLowest", "pricePlusPostageHighest", "distanceNearest" ] }, "minPrice": { "type": "number" }, "maxPrice": { "type": "number" }, "itemLocation": { "type": "string", "enum": [ "default", "domestic", "worldwide" ] }, "itemCondition": { "type": "string", "enum": [ "any", "new", "used" ] }, "conditionId": { "type": "integer", "minimum": 0 }, "buyingFormat": { "type": "string", "enum": [ "all", "auction", "buyItNow", "acceptsOffers" ] }, "sellerType": { "type": "string", "enum": [ "private", "business" ] }, "includeCompleteListing": { "type": "boolean" }, "sold": { "type": "boolean", "default": true }, "soldAfter": { "type": "string", "format": "date" }, "soldBefore": { "type": "string", "format": "date" }, "exactMatch": { "type": "boolean", "default": false }, "aspectFilter": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, "relevance": { "type": "boolean", "default": true } }, "additionalProperties": false }, "CardBatchRequest": { "type": "object", "required": [ "cards" ], "properties": { "cards": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "$ref": "#/components/schemas/CardInput" } }, "options": { "$ref": "#/components/schemas/CardBatchOptions" } } }, "CardInput": { "type": "object", "description": "Supply an exact keyword, or structured fields. subject is universal; player and character are convenient aliases.", "properties": { "reference": { "type": "string", "description": "Your inventory or correlation ID, echoed in the result." }, "keyword": { "type": "string", "maxLength": 300, "description": "Exact eBay search keyword. When present it overrides generated structured-field keywords." }, "subject": { "type": "string" }, "player": { "type": "string" }, "character": { "type": "string" }, "year": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "set": { "type": "string" }, "cardNumber": { "oneOf": [ { "type": "string" }, { "type": "number" } ] }, "parallel": { "type": "string" }, "grader": { "type": "string", "example": "PSA" }, "grade": { "oneOf": [ { "type": "string" }, { "type": "number" } ], "example": 10 } } }, "CardBatchOptions": { "type": "object", "properties": { "ebaySite": { "type": "string", "enum": [ "ebay.com", "ebay.co.uk", "ebay.de", "ebay.fr", "ebay.it", "ebay.es", "ebay.ca", "ebay.com.au" ] }, "count": { "type": "integer", "minimum": 1, "maximum": 240, "default": 60, "description": "Maximum sold comps inspected per card. Compact output is capped at 60." }, "itemCondition": { "type": "string", "enum": [ "any", "new", "used" ] }, "soldAfter": { "type": "string", "format": "date" }, "soldBefore": { "type": "string", "format": "date" }, "exactMatch": { "type": "boolean", "default": false, "description": "Remove eBay's explicit Results matching fewer words section for each card search." }, "relevance": { "type": "boolean", "default": true }, "outputMode": { "type": "string", "enum": [ "summary", "compact" ], "default": "summary", "description": "compact also returns compact sold-listing rows, including bestOfferAccepted, and is limited to 25 cards with count <= 60." } } }, "CardBatchAccepted": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "example": "queued" }, "totalCards": { "type": "integer" }, "billing": { "type": "string" }, "resultsUrl": { "type": "string" } } }, "CardBatchJob": { "type": "object", "properties": { "jobId": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "queued", "running", "done", "partial", "cancelled", "failed" ] }, "totalCards": { "type": "integer" }, "processedCards": { "type": "integer" }, "remainingCards": { "type": "integer" }, "succeededCards": { "type": "integer" }, "failedCards": { "type": "integer" }, "error": { "type": "string", "nullable": true }, "results": { "type": "array", "items": { "$ref": "#/components/schemas/CardBatchResult" } }, "upgradeUrl": { "type": "string", "format": "uri", "description": "Present when processing stopped because the account quota was exhausted." } } }, "CardBatchResult": { "type": "object", "required": [ "keyword", "ok" ], "properties": { "reference": { "type": "string" }, "card": { "$ref": "#/components/schemas/CardInput" }, "keyword": { "type": "string" }, "ok": { "type": "boolean" }, "totalResults": { "type": "string", "nullable": true }, "totalItems": { "type": "integer" }, "rawMedian": { "type": "number", "nullable": true }, "rawSampleCount": { "type": "integer", "nullable": true }, "summary": { "$ref": "#/components/schemas/PriceSummary" }, "cached": { "type": "boolean" }, "items": { "type": "array", "items": { "$ref": "#/components/schemas/CompactSoldItem" } }, "error": { "type": "string" }, "code": { "type": "string" } } }, "CompactSoldItem": { "type": "object", "properties": { "itemId": { "type": "string" }, "title": { "type": "string", "nullable": true }, "soldPrice": { "type": "string", "nullable": true }, "currency": { "type": "string", "nullable": true }, "shippingPrice": { "type": "string", "nullable": true }, "totalPrice": { "type": "string", "nullable": true }, "condition": { "type": "string", "nullable": true }, "bestOfferAccepted": { "type": "boolean", "nullable": true, "description": "true when eBay marked an accepted Best Offer; null otherwise. The accepted amount is not disclosed." }, "soldDate": { "type": "string", "nullable": true }, "sellerUsername": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true } } }, "ApiError": { "type": "object", "properties": { "error": { "type": "string" }, "code": { "type": "string" }, "retry_after": { "type": "integer", "description": "Seconds before a temporary rate_limited request may be retried." }, "reset_at": { "type": "string", "format": "date-time", "description": "Billing-cycle reset for quota_exceeded." }, "plan": { "type": "string" }, "quota": { "type": "integer" }, "used": { "type": "integer" }, "remaining": { "type": "integer" }, "rollover_balance": { "type": "integer", "description": "Temporary carried-over requests remaining." }, "upgrade_url": { "type": "string", "format": "uri", "description": "Plan-management URL for quota_exceeded." }, "credit_balance": { "type": "integer", "description": "Non-expiring purchased credits remaining." }, "purchase_credits_url": { "type": "string", "format": "uri", "description": "Credit purchase URL for quota_exceeded." }, "subscription_url": { "type": "string", "format": "uri", "description": "Shipping Rates plan URL for shipping_subscription_required or shipping_quota_exceeded." } } } } } }