{ "openapi": "3.1.0", "info": { "title": "Soldgraph API", "version": "1.0.0", "description": "Sold and active listings from eBay, Poshmark and Mercari (US); active listings only from Depop (US).", "contact": { "url": "https://soldgraph.com/docs" } }, "servers": [ { "url": "https://api.soldgraph.com/v1" } ], "security": [ { "bearer": [] } ], "paths": { "/ebay/sold": { "get": { "operationId": "ebay_sold", "tags": [ "eBay" ], "summary": "eBay sold listings", "description": "Search one page of eBay US sold listings by keyword. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/sold" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be ebay.", "schema": { "type": "string", "enum": [ "ebay" ], "default": "ebay" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "eBay's own condition groups. Send one or more, separated by commas, like new,open_box. new is Brand New, open_box is Open Box or New (Other), refurbished is every refurbished grade, used is Pre-Owned and for_parts is Parts Only. eBay applies the filter.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "new", "open_box", "refurbished", "used", "for_parts" ] }, "uniqueItems": true } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbaySoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "ebay", "country": "us", "query": "sony wh-1000xm5", "page": 1, "page_size": 40, "count": 1, "reported_total": 1, "next_page": null, "next_cursor": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "123456789012", "title": "Example eBay listing", "link": "https://www.ebay.com/itm/123456789012", "displayed_price": { "amount": 189, "currency": "USD" }, "displayed_price_text": "$189.00", "displayed_shipping": { "amount": 9.99, "currency": "USD" }, "shipping_text": "+$9.99 delivery", "sold_date": "2026-09-21", "sold_date_text": "Sep-21 14:35", "condition": "Pre-Owned", "seller_text": "sonyfan_outlet (2,418) 99.6%", "brand": null, "size": null, "image": "https://i.ebayimg.com/images/g/example/s-l500.jpg", "price": null, "shipping": null, "sold_at": null, "took_offer": null } ], "field_notes": "Unverified fields are null. Displayed prices are not verified accepted-offer prices." } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbaySoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/EbaySoldJob" } ] } } } } } } }, "/ebay/listings": { "get": { "operationId": "ebay_listings", "tags": [ "eBay" ], "summary": "eBay active listings", "description": "Search one page of eBay US active listings by keyword, in the sort order you pick. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/listings" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be ebay.", "schema": { "type": "string", "enum": [ "ebay" ], "default": "ebay" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "sort", "in": "query", "required": false, "description": "eBay's listing order. Promoted listings are included and flagged.", "schema": { "type": "string", "enum": [ "best_match", "newest", "price_asc", "ending_soon" ], "default": "best_match" } }, { "name": "condition", "in": "query", "required": false, "description": "eBay's own condition groups. Send one or more, separated by commas, like new,open_box. new is Brand New, open_box is Open Box or New (Other), refurbished is every refurbished grade, used is Pre-Owned and for_parts is Parts Only. eBay applies the filter.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "new", "open_box", "refurbished", "used", "for_parts" ] }, "uniqueItems": true } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbayListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "ebay", "country": "us", "query": "canon ae-1 program", "page": 1, "page_size": 40, "count": 1, "reported_total": 1, "next_page": null, "next_cursor": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "123456789012", "title": "Example eBay listing", "link": "https://www.ebay.com/itm/123456789012", "promoted": false, "format": "fixed_price", "displayed_price": { "amount": 189, "currency": "USD" }, "displayed_price_text": "$189.00", "displayed_shipping": { "amount": 0, "currency": "USD" }, "shipping_text": "Free delivery", "condition": "Pre-Owned", "brand": null, "size": null, "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": false, "seller_text": "filmcamerashop (1,204) 100%", "location_text": null, "image": "https://i.ebayimg.com/images/g/example/s-l500.jpg" } ], "field_notes": "Listings are in the marketplace's order; promoted listings are included and flagged. Unverified fields are null." } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbayListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/EbayListingsJob" } ] } } } } } } }, "/poshmark/sold": { "get": { "operationId": "poshmark_sold", "tags": [ "Poshmark" ], "summary": "Poshmark sold listings", "description": "Search one page of Poshmark US sold listings by keyword. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/poshmark-sold" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be poshmark.", "schema": { "type": "string", "enum": [ "poshmark" ], "default": "poshmark" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "One of Poshmark's own condition codes: nwt (new with tags), uln (like new), ug (good) or uf (fair). Rows use the same codes. Poshmark filters one condition at a time, so more than one returns 422.", "schema": { "type": "string", "enum": [ "nwt", "uln", "ug", "uf" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's next_cursor. Leave it out on page 1. Required on every later page.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoshmarkSoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "poshmark", "country": "us", "query": "Levis 501", "page": 1, "page_size": 48, "count": 1, "reported_total": 1, "next_page": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "000000000000000000000001", "title": "Example Levi’s 501 jeans", "link": "https://poshmark.com/listing/000000000000000000000001", "displayed_price": { "amount": 35, "currency": "USD" }, "displayed_price_text": "$35.00", "displayed_shipping": null, "shipping_text": null, "sold_date": "2026-09-28", "sold_date_text": "2026-09-28T22:16:54-07:00", "condition": "ug", "seller_text": "closetofkate", "brand": "Levi's", "size": "32", "image": "https://di2ponv0v5otw.cloudfront.net/posts/example.jpg", "price": null, "shipping": null, "sold_at": null, "took_offer": null } ], "field_notes": "Displayed prices are listing asks, not verified transaction or accepted-offer amounts. sold_date_text is the inventory sold_out status change time; unverified fields are null. Only listings with sold_out inventory are included.", "next_cursor": null } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoshmarkSoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PoshmarkSoldJob" } ] } } } } } } }, "/poshmark/listings": { "get": { "operationId": "poshmark_listings", "tags": [ "Poshmark" ], "summary": "Poshmark active listings", "description": "Search one page of Poshmark US active listings by keyword, in the sort order you pick. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/poshmark-listings" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be poshmark.", "schema": { "type": "string", "enum": [ "poshmark" ], "default": "poshmark" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "sort", "in": "query", "required": false, "description": "Poshmark's listing order. ending_soon isn't available on Poshmark and returns 422.", "schema": { "type": "string", "enum": [ "best_match", "newest", "price_asc" ], "default": "best_match" } }, { "name": "condition", "in": "query", "required": false, "description": "One of Poshmark's own condition codes: nwt (new with tags), uln (like new), ug (good) or uf (fair). Rows use the same codes. Poshmark filters one condition at a time, so more than one returns 422.", "schema": { "type": "string", "enum": [ "nwt", "uln", "ug", "uf" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's next_cursor. Leave it out on page 1. Required on every later page.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoshmarkListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "poshmark", "country": "us", "query": "Levis 501", "page": 1, "page_size": 48, "count": 1, "reported_total": 1, "next_page": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "000000000000000000000002", "title": "Example Levi’s 501 jeans", "link": "https://poshmark.com/listing/000000000000000000000002", "promoted": null, "format": "fixed_price", "displayed_price": { "amount": 42, "currency": "USD" }, "displayed_price_text": "$42.00", "displayed_shipping": null, "shipping_text": null, "condition": "uln", "brand": "Levi's", "size": "30", "listed_at": "2026-09-27T10:04:12-07:00", "bid_count": null, "ends_at": null, "best_offer": null, "seller_text": "example_closet", "location_text": null, "image": "https://di2ponv0v5otw.cloudfront.net/posts/example.jpg" } ], "field_notes": "Listings are in the marketplace's order and priced at the seller's current ask. Only available inventory is included; unverified fields are null.", "next_cursor": null } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PoshmarkListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/PoshmarkListingsJob" } ] } } } } } } }, "/mercari/sold": { "get": { "operationId": "mercari_sold", "tags": [ "Mercari" ], "summary": "Mercari sold listings", "description": "Search one page of Mercari US sold listings by keyword, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/mercari-sold" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be mercari.", "schema": { "type": "string", "enum": [ "mercari" ], "default": "mercari" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "One Mercari condition: new, like_new, good, fair or poor. Rows return Mercari's label and condition_id.", "schema": { "type": "string", "enum": [ "new", "like_new", "good", "fair", "poor" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's next_cursor. Leave it out on page 1. Keep every other parameter the same.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "count", "in": "query", "required": false, "description": "Most rows per page. Mercari can return fewer.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Mercari's result order. newest sorts by when the listing was created. recently_sold sorts by Mercari's sold time.", "schema": { "type": "string", "enum": [ "best_match", "newest", "price_asc", "price_desc", "most_popular", "recently_sold" ], "default": "recently_sold" } }, { "name": "category_id", "in": "query", "required": false, "description": "Mercari numeric category ID. Optional.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "brand_id", "in": "query", "required": false, "description": "Mercari numeric brand ID. Optional.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MercariSoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "mercari", "country": "us", "query": "sony headphones", "page": 1, "page_size": 1, "count": 1, "reported_total": 1, "next_page": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "m00000000001", "title": "Illustrative Sony headphones listing", "link": "https://www.mercari.com/us/item/m00000000001/", "displayed_price": { "amount": 35, "currency": "USD" }, "displayed_price_text": "$35.00", "displayed_shipping": null, "shipping_text": null, "sold_date": "2026-09-28", "sold_date_text": "2026-09-28T12:00:00+00:00", "condition": "Good", "seller_text": "123456789", "brand": null, "size": null, "image": null, "price": null, "shipping": null, "sold_at": null, "took_offer": null, "condition_id": 3, "brand_id": 1, "category_id": 1594, "seller_id": "123456789", "status": "sold" } ], "field_notes": "Displayed prices are marketplace listing amounts, not independently verified transaction or accepted-offer amounts. Sold timestamps are source-reported and may be absent. Trading items are excluded. Brand/category IDs are source IDs; labels and size are null. Reported totals may be capped. Results cover one source page only.", "next_cursor": null } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MercariSoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MercariSoldJob" } ] } } } } } } }, "/mercari/listings": { "get": { "operationId": "mercari_listings", "tags": [ "Mercari" ], "summary": "Mercari active listings", "description": "Search one page of Mercari US active listings by keyword, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/mercari-listings" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be mercari.", "schema": { "type": "string", "enum": [ "mercari" ], "default": "mercari" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "One Mercari condition: new, like_new, good, fair or poor. Rows return Mercari's label and condition_id.", "schema": { "type": "string", "enum": [ "new", "like_new", "good", "fair", "poor" ] } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's next_cursor. Leave it out on page 1. Keep every other parameter the same.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "count", "in": "query", "required": false, "description": "Most rows per page. Mercari can return fewer.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 100 } }, { "name": "sort", "in": "query", "required": false, "description": "Mercari's result order. newest sorts by when the listing was created.", "schema": { "type": "string", "enum": [ "best_match", "newest", "price_asc", "price_desc", "most_popular" ], "default": "best_match" } }, { "name": "category_id", "in": "query", "required": false, "description": "Mercari numeric category ID. Optional.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "brand_id", "in": "query", "required": false, "description": "Mercari numeric brand ID. Optional.", "schema": { "type": "integer", "minimum": 1, "maximum": 2147483647 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MercariListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "mercari", "country": "us", "query": "sony headphones", "page": 1, "page_size": 1, "count": 1, "reported_total": 1, "next_page": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "m00000000001", "title": "Illustrative Sony headphones listing", "link": "https://www.mercari.com/us/item/m00000000001/", "promoted": null, "format": "fixed_price", "displayed_price": { "amount": 42, "currency": "USD" }, "displayed_price_text": "$42.00", "displayed_shipping": null, "shipping_text": null, "condition": "Good", "brand": null, "size": null, "listed_at": "2026-09-27T10:04:12-07:00", "bid_count": null, "ends_at": null, "best_offer": null, "seller_text": "123456789", "location_text": null, "image": null, "condition_id": 3, "brand_id": 1, "category_id": 1594, "seller_id": "123456789", "status": "active" } ], "field_notes": "Displayed prices are marketplace listing amounts, not independently verified transaction or accepted-offer amounts. Sold timestamps are source-reported and may be absent. Trading items are excluded. Brand/category IDs are source IDs; labels and size are null. Reported totals may be capped. Results cover one source page only.", "next_cursor": null } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MercariListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/MercariListingsJob" } ] } } } } } } }, "/depop/listings": { "get": { "operationId": "depop_listings", "tags": [ "Depop" ], "summary": "Depop active listings", "description": "Search one page of Depop US active listings by keyword, up to 100 rows. Pages use a cursor. Results are cached for 15 minutes. A cache miss returns 202 and a job to poll.", "externalDocs": { "url": "https://soldgraph.com/docs/api/depop-listings" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be depop.", "schema": { "type": "string", "enum": [ "depop" ], "default": "depop" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "One Depop condition: brand_new, used_like_new, used_excellent, used_good or used_fair. Rows return the same codes.", "schema": { "type": "string", "enum": [ "brand_new", "used_like_new", "used_excellent", "used_good", "used_fair" ] } }, { "name": "count", "in": "query", "required": false, "description": "Most rows per page. Depop can return fewer.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 } }, { "name": "cursor", "in": "query", "required": false, "description": "The previous page's next_cursor. Leave it out on page 1. Keep the query, filters and count the same.", "schema": { "type": "string", "minLength": 1, "maxLength": 2048 } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepopListingsJob" }, "example": { "request_id": "example-depop-search", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "depop", "country": "us", "query": "nike", "page": 1, "page_size": 5, "count": 5, "reported_total": 2863606, "next_page": 2, "next_cursor": "WyJNbncxZkRFM09UQTNNRGswTlRBLkJPT1NURURfRVhIQVVTVEVELjAiLCAiNzIyMGVhY2U5NDgxZWU5Y2E5ZDllNjRhNzE3YmE5ZTk2MWRmZmM2ZDg3OTRmNDU4ODNkY2E2ZDdiMjQ3NjRlZiIsIDJd", "collected_at": "2026-09-29T19:17:31.799685+00:00", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "929885807", "title": "Nike Bra in solid light green Size: M 💚 #activewear #sports #nike #sportbra Brand new", "link": "https://www.depop.com/products/lovexzat-nike-bra-in-solid-light-4c6d/", "displayed_price": { "amount": 5.95, "currency": "USD" }, "displayed_price_text": "$5.95", "price_includes": [ "buyer_fee" ], "displayed_shipping": null, "shipping_text": null, "condition": "brand_new", "seller_text": null, "brand": "Nike", "size": "M", "image": "https://media-photos.depop.com/r1/7548776/4806392865_e376f6e8a5e14144b78062921e1cd94e/P0.jpg", "status": "active", "promoted": false, "format": "fixed_price", "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": null, "location_text": "Los Angeles, United States" }, { "id": "930772677", "title": "Nike SB hoodie with white and yellow 'NIKE SB' logo, size L #skateboarding #sb", "link": "https://www.depop.com/products/abbimjelsema-nike-sb-hoodie-with-white-7e9d/", "displayed_price": { "amount": 5.95, "currency": "USD" }, "displayed_price_text": "$5.95", "price_includes": [ "buyer_fee" ], "displayed_shipping": null, "shipping_text": null, "condition": "used_fair", "seller_text": null, "brand": "Nike", "size": "L", "image": "https://media-photos.depop.com/r1/218735601/4811656506_4d0e4793b3b24c6686684127e03e96ed/P0.jpg", "status": "active", "promoted": false, "format": "fixed_price", "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": null, "location_text": "Byron Center, United States" }, { "id": "930226367", "title": "Nike Tech Fleece black sweatpants size XS #techfleece #nike#black#tech#pants", "link": "https://www.depop.com/products/kanuc2i-nike-tech-fleece-black-sweatpants-b7e1/", "displayed_price": { "amount": 19.6, "currency": "USD" }, "displayed_price_text": "$19.60", "price_includes": [ "buyer_fee" ], "displayed_shipping": null, "shipping_text": null, "condition": "used_good", "seller_text": null, "brand": "Nike", "size": "XS", "image": "https://media-photos.depop.com/b1/47345678/4808288131_3f9d82598a9f4450b808552d9e1e3283/P0.jpg", "status": "active", "promoted": false, "format": "fixed_price", "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": null, "location_text": "Portland, United States" }, { "id": "929853097", "title": "grey nike pros size small worn a few times!! #nike #nikepros #grey", "link": "https://www.depop.com/products/mollygraceaver5-grey-nike-pros-size-small-448f/", "displayed_price": { "amount": 5.95, "currency": "USD" }, "displayed_price_text": "$5.95", "price_includes": [ "buyer_fee" ], "displayed_shipping": null, "shipping_text": null, "condition": "used_excellent", "seller_text": null, "brand": "Nike", "size": "One size", "image": "https://media-photos.depop.com/r1/370197255/4806213953_fcdec04586e846df916b12f133ba429d/P0.jpg", "status": "active", "promoted": false, "format": "fixed_price", "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": null, "location_text": "Ona, United States" }, { "id": "930263070", "title": "Nike black hoodie Size XL men’s used #athleisure #nike #hoodie #sweatshirt", "link": "https://www.depop.com/products/throwbakkkingz-nike-black-hoodie-size-xl-aef6/", "displayed_price": { "amount": 7, "currency": "USD" }, "displayed_price_text": "$7.00", "price_includes": [ "buyer_fee" ], "displayed_shipping": null, "shipping_text": null, "condition": "used_fair", "seller_text": null, "brand": "Nike", "size": "XL", "image": "https://media-photos.depop.com/b1/37215522/4808493787_8d99ee61ab824899a0f459149b19efc3/P0.jpg", "status": "active", "promoted": false, "format": "fixed_price", "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": null, "location_text": "Olympia, United States" } ], "field_notes": "Active listings only. displayed_price is Depop's USD headline amount; price_includes identifies fees included by the source. Price bounds apply to source search prices, which may differ from the headline. Shipping, seller identity and listing timestamps are unverified and null. Source order is preserved. Totals may be absent on later pages. No transaction price or sold-search capability is provided." } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepopListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/DepopListingsJob" } ] } } } } } } }, "/sold": { "get": { "operationId": "legacy_sold", "tags": [ "eBay" ], "summary": "Legacy alias of /v1/ebay/sold", "description": "Old path for /v1/ebay/sold. Same cache, billing and idempotency. No redirect. Use /v1/ebay/sold in new code.", "externalDocs": { "url": "https://soldgraph.com/docs/api/sold" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be ebay.", "schema": { "type": "string", "enum": [ "ebay" ], "default": "ebay" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "condition", "in": "query", "required": false, "description": "eBay's own condition groups. Send one or more, separated by commas, like new,open_box. new is Brand New, open_box is Open Box or New (Other), refurbished is every refurbished grade, used is Pre-Owned and for_parts is Parts Only. eBay applies the filter.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "new", "open_box", "refurbished", "used", "for_parts" ] }, "uniqueItems": true } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbaySoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "ebay", "country": "us", "query": "sony wh-1000xm5", "page": 1, "page_size": 40, "count": 1, "reported_total": 1, "next_page": null, "next_cursor": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "123456789012", "title": "Example eBay listing", "link": "https://www.ebay.com/itm/123456789012", "displayed_price": { "amount": 189, "currency": "USD" }, "displayed_price_text": "$189.00", "displayed_shipping": { "amount": 9.99, "currency": "USD" }, "shipping_text": "+$9.99 delivery", "sold_date": "2026-09-21", "sold_date_text": "Sep-21 14:35", "condition": "Pre-Owned", "seller_text": "sonyfan_outlet (2,418) 99.6%", "brand": null, "size": null, "image": "https://i.ebayimg.com/images/g/example/s-l500.jpg", "price": null, "shipping": null, "sold_at": null, "took_offer": null } ], "field_notes": "Unverified fields are null. Displayed prices are not verified accepted-offer prices." } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbaySoldJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/EbaySoldJob" } ] } } } } }, "deprecated": true } }, "/listings": { "get": { "operationId": "legacy_listings", "tags": [ "eBay" ], "summary": "Legacy alias of /v1/ebay/listings", "description": "Old path for /v1/ebay/listings. Same cache, billing and idempotency. No redirect. Use /v1/ebay/listings in new code.", "externalDocs": { "url": "https://soldgraph.com/docs/api/listings" }, "parameters": [ { "name": "q", "in": "query", "required": true, "description": "Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.", "schema": { "type": "string", "minLength": 1, "maxLength": 200 } }, { "name": "page", "in": "query", "required": false, "description": "Source page to fetch. On Poshmark, Mercari and Depop, pages after 1 also need cursor.", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 1 } }, { "name": "min_price", "in": "query", "required": false, "description": "Lowest price, in whole US dollars. Optional. Must not be more than max_price. You can send it without max_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "max_price", "in": "query", "required": false, "description": "Highest price, in whole US dollars. Optional. You can send it without min_price.", "schema": { "type": "integer", "minimum": 0, "maximum": 1000000 } }, { "name": "marketplace", "in": "query", "required": false, "description": "Optional. If sent, it must be ebay.", "schema": { "type": "string", "enum": [ "ebay" ], "default": "ebay" } }, { "name": "country", "in": "query", "required": false, "description": "Only us is supported.", "schema": { "type": "string", "enum": [ "us" ], "default": "us" } }, { "name": "sort", "in": "query", "required": false, "description": "eBay's listing order. Promoted listings are included and flagged.", "schema": { "type": "string", "enum": [ "best_match", "newest", "price_asc", "ending_soon" ], "default": "best_match" } }, { "name": "condition", "in": "query", "required": false, "description": "eBay's own condition groups. Send one or more, separated by commas, like new,open_box. new is Brand New, open_box is Open Box or New (Other), refurbished is every refurbished grade, used is Pre-Owned and for_parts is Parts Only. eBay applies the filter.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string", "enum": [ "new", "open_box", "refurbished", "used", "for_parts" ] }, "uniqueItems": true } }, { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Send the same key when you retry the same search, so you aren't charged twice. 1–128 printable ASCII characters, no spaces.", "schema": { "type": "string", "pattern": "^[!-~]{1,128}$" } } ], "responses": { "200": { "description": "Complete, including cache hits. Costs 1 request.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbayListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "complete", "credits": 1, "cached": false, "result": { "provider": "ebay", "country": "us", "query": "canon ae-1 program", "page": 1, "page_size": 40, "count": 1, "reported_total": 1, "next_page": null, "next_cursor": null, "collected_at": "2026-09-23T14:02:11Z", "schema_version": 1, "completeness": "provider_page_only", "data": [ { "id": "123456789012", "title": "Example eBay listing", "link": "https://www.ebay.com/itm/123456789012", "promoted": false, "format": "fixed_price", "displayed_price": { "amount": 189, "currency": "USD" }, "displayed_price_text": "$189.00", "displayed_shipping": { "amount": 0, "currency": "USD" }, "shipping_text": "Free delivery", "condition": "Pre-Owned", "brand": null, "size": null, "listed_at": null, "bid_count": null, "ends_at": null, "best_offer": false, "seller_text": "filmcamerashop (1,204) 100%", "location_text": null, "image": "https://i.ebayimg.com/images/g/example/s-l500.jpg" } ], "field_notes": "Listings are in the marketplace's order; promoted listings are included and flagged. Unverified fields are null." } } } } }, "202": { "description": "Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Location": { "description": "Job path, like /v1/jobs/{id}.", "schema": { "type": "string" } }, "Retry-After": { "description": "Always 2. Prefer long-polling with ?wait=20.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EbayListingsJob" }, "example": { "request_id": "00000000-0000-4000-8000-000000000001", "status": "pending", "credits": 0, "cached": false, "poll_url": "/v1/jobs/00000000-0000-4000-8000-000000000001" } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "idempotency_conflict: This Idempotency-Key was already used with different search parameters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. 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.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance for the rolling 30 days is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/Error" }, { "$ref": "#/components/schemas/EbayListingsJob" } ] } } } } }, "deprecated": true } }, "/jobs/{id}": { "get": { "operationId": "get_job", "tags": [ "Jobs" ], "summary": "Get a search's status and result", "description": "Returns HTTP 200 whether the job is pending, complete or failed, so check status. Polling costs no requests but counts toward the per-minute rate limit.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "wait", "in": "query", "description": "Seconds to hold the request open until the job settles (long-poll).", "schema": { "type": "integer", "minimum": 0, "maximum": 20, "default": 0 } } ], "responses": { "200": { "description": "The job. Check status: pending, complete or failed.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/EbaySoldJob" }, { "$ref": "#/components/schemas/EbayListingsJob" }, { "$ref": "#/components/schemas/PoshmarkSoldJob" }, { "$ref": "#/components/schemas/PoshmarkListingsJob" }, { "$ref": "#/components/schemas/MercariSoldJob" }, { "$ref": "#/components/schemas/MercariListingsJob" }, { "$ref": "#/components/schemas/DepopListingsJob" } ] } } } }, "401": { "description": "invalid_api_key: The API key is missing, malformed or revoked.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "403": { "description": "origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "not_found: No such path. request_not_found: The job ID is malformed, unknown, or belongs to another account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "405": { "description": "method_not_allowed: Only GET is supported.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "414": { "description": "uri_too_long: The query string is longer than 2,048 characters.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "invalid_wait: wait must be a whole number from 0 to 20.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "rate_limited: More than 60 API calls this minute for your account.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support.", "headers": { "X-Request-Id": { "description": "Unique ID for this response. Include it when you contact support.", "schema": { "type": "string" } }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearer": { "type": "http", "scheme": "bearer", "description": "An API key from the Soldgraph dashboard, starting with sg_." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "invalid_api_key", "account_suspended", "origin_not_allowed", "not_found", "request_not_found", "method_not_allowed", "idempotency_conflict", "uri_too_long", "unsupported_or_invalid_query", "duplicate_parameter", "sort_not_implemented", "invalid_idempotency_key", "invalid_wait", "rate_limited", "quota_exceeded", "too_many_pending", "upstream_daily_limit", "queue_full", "collection_unavailable", "storage_unavailable", "origin_unavailable", "service_unconfigured" ] } } } } }, "Money": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number" }, "currency": { "type": "string", "description": "ISO 4217 code, like USD." } } }, "EbaySoldRow": { "type": "object", "required": [ "id", "title", "link", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "sold_date", "sold_date_text", "condition", "seller_text", "brand", "size", "image", "price", "shipping", "sold_at", "took_offer" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "displayed_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "{ amount, currency } parsed from the price shown. Null if it couldn't be read. Null when eBay shows a price range for a multi-variation listing (\"$247.00 to $911.00\"): the amount wouldn't say which variant. The range stays in displayed_price_text." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text as shown, like $189.00." }, "displayed_shipping": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "{ amount, currency } read from exact shipping text, like +$9.99 delivery. Free delivery is 0. Estimates and Shipping not specified are null." }, "shipping_text": { "type": [ "string", "null" ], "description": "Shipping text as shown, like +$9.99 delivery or Free delivery." }, "sold_date": { "type": [ "string", "null" ], "description": "Sale date as YYYY-MM-DD. eBay's text has no year, so we use the most recent date that matches." }, "sold_date_text": { "type": [ "string", "null" ], "description": "Sold date text as shown, like Sep-21 14:35. eBay leaves out the year." }, "condition": { "type": [ "string", "null" ], "description": "eBay's condition text as shown, like Pre-Owned." }, "seller_text": { "type": [ "string", "null" ], "description": "Seller text as eBay shows it: username, feedback count and positive percentage, e.g. clutch_supply (1,325) 99.7%." }, "brand": { "type": "null", "description": "Always null on eBay." }, "size": { "type": "null", "description": "Always null on eBay." }, "image": { "type": [ "string", "null" ], "description": "Image URL on i.ebayimg.com." }, "price": { "type": "null", "description": "Always null. Reserved for a verified sale price." }, "shipping": { "type": "null", "description": "Always null. Reserved for a verified shipping amount." }, "sold_at": { "type": "null", "description": "Always null. Reserved for a verified sale time." }, "took_offer": { "type": "null", "description": "Always null. Reserved for whether a Best Offer was accepted." } } }, "EbaySoldPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows per page, as eBay reports it." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EbaySoldRow" } } } }, "EbaySoldJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/EbaySoldPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "EbayListingsRow": { "type": "object", "required": [ "id", "title", "link", "promoted", "format", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "condition", "brand", "size", "listed_at", "bid_count", "ends_at", "best_offer", "seller_text", "location_text", "image" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "promoted": { "type": "boolean", "description": "True for a sponsored placement." }, "format": { "type": "string", "description": "auction when the listing shows bids or an end time, otherwise fixed_price." }, "displayed_price": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "{ amount, currency } parsed from the price shown: the asking price or current bid. Null if it couldn't be read. Null when eBay shows a price range for a multi-variation listing (\"$247.00 to $911.00\"): the amount wouldn't say which variant. The range stays in displayed_price_text." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text as shown, like $189.00." }, "displayed_shipping": { "oneOf": [ { "$ref": "#/components/schemas/Money" }, { "type": "null" } ], "description": "{ amount, currency } read from exact shipping text, like +$9.99 delivery. Free delivery is 0. Estimates and Shipping not specified are null." }, "shipping_text": { "type": [ "string", "null" ], "description": "Shipping text as shown, like +$9.99 delivery or Free delivery." }, "condition": { "type": [ "string", "null" ], "description": "eBay's condition text as shown, like Pre-Owned." }, "brand": { "type": "null", "description": "Always null on eBay." }, "size": { "type": "null", "description": "Always null on eBay." }, "listed_at": { "type": "null", "description": "Always null on eBay." }, "bid_count": { "type": [ "integer", "null" ], "description": "Number of bids, for auctions." }, "ends_at": { "type": [ "string", "null" ], "description": "Auction end time, ISO 8601 UTC." }, "best_offer": { "type": "boolean", "description": "True when the seller accepts Best Offers." }, "seller_text": { "type": [ "string", "null" ], "description": "Seller text as eBay shows it: username, feedback count and positive percentage, e.g. clutch_supply (1,325) 99.7%." }, "location_text": { "type": [ "string", "null" ], "description": "Item location text as shown." }, "image": { "type": [ "string", "null" ], "description": "Image URL on i.ebayimg.com." } } }, "EbayListingsPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows per page, as eBay reports it." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/EbayListingsRow" } } } }, "EbayListingsJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/EbayListingsPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "PoshmarkSoldRow": { "type": "object", "required": [ "id", "title", "link", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "sold_date", "sold_date_text", "condition", "seller_text", "brand", "size", "image", "price", "shipping", "sold_at", "took_offer" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "displayed_price": { "$ref": "#/components/schemas/Money", "description": "{ amount, currency } of the listing's asking price. Not what the buyer paid." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text as shown, like $189.00." }, "displayed_shipping": { "type": "null", "description": "Always null on Poshmark." }, "shipping_text": { "type": "null", "description": "Always null on Poshmark." }, "sold_date": { "type": "string", "description": "Date part of sold_date_text, as YYYY-MM-DD." }, "sold_date_text": { "type": "string", "description": "When the listing's inventory changed to sold out, as an ISO 8601 timestamp. Not a verified sale time." }, "condition": { "type": [ "string", "null" ], "description": "Poshmark's own condition code, as Poshmark returns it, like nwt or ug. See condition codes." }, "seller_text": { "type": [ "string", "null" ], "description": "The seller's Poshmark username." }, "brand": { "type": [ "string", "null" ], "description": "Brand as the seller entered it." }, "size": { "type": [ "string", "null" ], "description": "Size as the seller entered it." }, "image": { "type": [ "string", "null" ], "description": "Image URL on Poshmark's image CDN." }, "price": { "type": "null", "description": "Always null. Reserved for a verified sale price." }, "shipping": { "type": "null", "description": "Always null. Reserved for a verified shipping amount." }, "sold_at": { "type": "null", "description": "Always null. Reserved for a verified sale time." }, "took_offer": { "type": "null", "description": "Always null. Reserved for whether a Best Offer was accepted." } } }, "PoshmarkSoldPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "next_cursor", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows Poshmark returned before we removed listings that aren't sold. It can be larger than count." }, "next_cursor": { "type": [ "string", "null" ], "description": "Send this as cursor, with page=next_page, to get the next page. Null on the last page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoshmarkSoldRow" } } } }, "PoshmarkSoldJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/PoshmarkSoldPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "PoshmarkListingsRow": { "type": "object", "required": [ "id", "title", "link", "promoted", "format", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "condition", "brand", "size", "listed_at", "bid_count", "ends_at", "best_offer", "seller_text", "location_text", "image" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "promoted": { "type": "null", "description": "Always null on Poshmark." }, "format": { "type": "string", "description": "Always fixed_price on Poshmark." }, "displayed_price": { "$ref": "#/components/schemas/Money", "description": "{ amount, currency } of the seller's current asking price." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text, like $35.00." }, "displayed_shipping": { "type": "null", "description": "Always null on Poshmark." }, "shipping_text": { "type": "null", "description": "Always null on Poshmark." }, "condition": { "type": [ "string", "null" ], "description": "Poshmark's own condition code, as Poshmark returns it, like nwt or ug. See condition codes." }, "brand": { "type": [ "string", "null" ], "description": "Brand as the seller entered it." }, "size": { "type": [ "string", "null" ], "description": "Size as the seller entered it." }, "listed_at": { "type": [ "string", "null" ], "description": "When the listing was published, as an ISO 8601 timestamp." }, "bid_count": { "type": "null", "description": "Always null on Poshmark." }, "ends_at": { "type": "null", "description": "Always null on Poshmark." }, "best_offer": { "type": "null", "description": "Always null on Poshmark." }, "seller_text": { "type": [ "string", "null" ], "description": "The seller's Poshmark username." }, "location_text": { "type": "null", "description": "Always null on Poshmark." }, "image": { "type": [ "string", "null" ], "description": "Image URL on Poshmark's image CDN." } } }, "PoshmarkListingsPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "next_cursor", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows Poshmark returned before we removed listings that aren't for sale. It can be larger than count." }, "next_cursor": { "type": [ "string", "null" ], "description": "Send this as cursor, with page=next_page, to get the next page. Null on the last page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/PoshmarkListingsRow" } } } }, "PoshmarkListingsJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/PoshmarkListingsPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "MercariSoldRow": { "type": "object", "required": [ "id", "title", "link", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "sold_date", "sold_date_text", "condition", "seller_text", "brand", "size", "image", "price", "shipping", "sold_at", "took_offer", "status", "seller_id", "condition_id", "category_id", "brand_id" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "displayed_price": { "$ref": "#/components/schemas/Money", "description": "{ amount, currency } of the price Mercari shows. It can differ from what the buyer paid." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text as shown, like $189.00." }, "displayed_shipping": { "type": "null", "description": "Always null on Mercari." }, "shipping_text": { "type": "null", "description": "Always null on Mercari." }, "sold_date": { "type": [ "string", "null" ], "description": "The date part of sold_date_text, as YYYY-MM-DD. Null when Mercari doesn't report a sold time." }, "sold_date_text": { "type": [ "string", "null" ], "description": "The sold time Mercari reports, as a UTC timestamp. Null when Mercari doesn't report one." }, "condition": { "type": [ "string", "null" ], "description": "Mercari's condition label: New, Like New, Good, Fair or Poor." }, "seller_text": { "type": [ "string", "null" ], "description": "The seller's Mercari ID, as a string." }, "brand": { "type": "null", "description": "Always null on Mercari. Search doesn't return the brand name." }, "size": { "type": "null", "description": "Always null on Mercari. Search doesn't return the size." }, "image": { "type": [ "string", "null" ], "description": "Image URL on Mercari's image CDN." }, "price": { "type": "null", "description": "Always null. Reserved for a verified sale price." }, "shipping": { "type": "null", "description": "Always null. Reserved for a verified shipping amount." }, "sold_at": { "type": "null", "description": "Always null. Reserved for a verified sale time." }, "took_offer": { "type": "null", "description": "Always null. Reserved for whether a Best Offer was accepted." }, "status": { "type": "string", "description": "Always sold on this route. Listings with a sale still in progress are left out." }, "seller_id": { "type": [ "string", "null" ], "description": "The seller's Mercari ID." }, "condition_id": { "type": [ "integer", "null" ], "description": "Mercari's condition number: 1 new, 2 like new, 3 good, 4 fair, 5 poor." }, "category_id": { "type": [ "integer", "null" ], "description": "Mercari's category ID for the listing." }, "brand_id": { "type": [ "integer", "null" ], "description": "Mercari's brand ID. The brand name isn't returned." } } }, "MercariSoldPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "next_cursor", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows Mercari returned before we removed listings that aren't sold. It can be larger than count." }, "next_cursor": { "type": [ "string", "null" ], "description": "Send this as cursor, with page=next_page, to get the next page. Null on the last page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MercariSoldRow" } } } }, "MercariSoldJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/MercariSoldPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "MercariListingsRow": { "type": "object", "required": [ "id", "title", "link", "promoted", "format", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "condition", "brand", "size", "listed_at", "bid_count", "ends_at", "best_offer", "seller_text", "location_text", "image", "status", "seller_id", "condition_id", "category_id", "brand_id" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Listing title as shown." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "promoted": { "type": "null", "description": "Always null on Mercari." }, "format": { "type": "string", "description": "Always fixed_price on Mercari." }, "displayed_price": { "$ref": "#/components/schemas/Money", "description": "{ amount, currency } of the price Mercari shows." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The price text, like $35.00." }, "displayed_shipping": { "type": "null", "description": "Always null on Mercari." }, "shipping_text": { "type": "null", "description": "Always null on Mercari." }, "condition": { "type": [ "string", "null" ], "description": "Mercari's condition label: New, Like New, Good, Fair or Poor." }, "brand": { "type": "null", "description": "Always null on Mercari. Search doesn't return the brand name." }, "size": { "type": "null", "description": "Always null on Mercari. Search doesn't return the size." }, "listed_at": { "type": [ "string", "null" ], "description": "When the listing was published, as an ISO 8601 timestamp." }, "bid_count": { "type": "null", "description": "Always null on Mercari." }, "ends_at": { "type": "null", "description": "Always null on Mercari." }, "best_offer": { "type": "null", "description": "Always null on Mercari." }, "seller_text": { "type": [ "string", "null" ], "description": "The seller's Mercari ID, as a string." }, "location_text": { "type": "null", "description": "Always null on Mercari." }, "image": { "type": [ "string", "null" ], "description": "Image URL on Mercari's image CDN." }, "status": { "type": "string", "description": "Always active on this route. Listings with a sale in progress are left out." }, "seller_id": { "type": [ "string", "null" ], "description": "The seller's Mercari ID." }, "condition_id": { "type": [ "integer", "null" ], "description": "Mercari's condition number: 1 new, 2 like new, 3 good, 4 fair, 5 poor." }, "category_id": { "type": [ "integer", "null" ], "description": "Mercari's category ID for the listing." }, "brand_id": { "type": [ "integer", "null" ], "description": "Mercari's brand ID. The brand name isn't returned." } } }, "MercariListingsPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "next_cursor", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": "integer", "description": "Total matches the marketplace reports for the search. It may be rounded or capped." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows Mercari returned before we removed listings that aren't for sale. It can be larger than count." }, "next_cursor": { "type": [ "string", "null" ], "description": "Send this as cursor, with page=next_page, to get the next page. Null on the last page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MercariListingsRow" } } } }, "MercariListingsJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/MercariListingsPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } }, "DepopListingsRow": { "type": "object", "required": [ "id", "title", "link", "promoted", "format", "displayed_price", "displayed_price_text", "displayed_shipping", "shipping_text", "condition", "brand", "size", "listed_at", "bid_count", "ends_at", "best_offer", "seller_text", "location_text", "image", "status", "price_includes" ], "properties": { "id": { "type": "string", "description": "The marketplace's listing ID." }, "title": { "type": [ "string", "null" ], "description": "Depop's listing description, up to 2,000 characters." }, "link": { "type": "string", "description": "URL of the listing on the marketplace." }, "promoted": { "type": [ "boolean", "null" ], "description": "Whether Depop marks the listing as boosted." }, "format": { "type": "string", "description": "Always fixed_price on Depop." }, "displayed_price": { "$ref": "#/components/schemas/Money", "description": "{ amount, currency } of Depop's headline price in USD. It includes the parts listed in price_includes. It isn't what a buyer paid." }, "displayed_price_text": { "type": [ "string", "null" ], "description": "The headline price as text." }, "displayed_shipping": { "type": "null", "description": "Always null on Depop. We can't verify the shipping amount." }, "shipping_text": { "type": "null", "description": "Always null on Depop. We can't verify the shipping amount." }, "condition": { "type": [ "string", "null" ], "description": "Depop's condition code, like used_good." }, "brand": { "type": [ "string", "null" ], "description": "The brand Depop shows, when there is one." }, "size": { "type": [ "string", "null" ], "description": "The sizes available, when Depop lists them." }, "listed_at": { "type": "null", "description": "Always null on Depop. We can't verify when the listing was created." }, "bid_count": { "type": "null", "description": "Always null on Depop." }, "ends_at": { "type": "null", "description": "Always null on Depop." }, "best_offer": { "type": "null", "description": "Always null on Depop." }, "seller_text": { "type": "null", "description": "Always null on Depop. Search doesn't give a seller we can verify." }, "location_text": { "type": [ "string", "null" ], "description": "The location Depop shows, when there is one." }, "image": { "type": [ "string", "null" ], "description": "Image URL on Depop's photo CDN." }, "status": { "type": "string", "description": "Always active." }, "price_includes": { "type": "array", "items": { "type": "string" }, "description": "What the headline price includes: buyer_fee, shipping_price, tax, or a mix. An empty array means none of them." } } }, "DepopListingsPage": { "type": "object", "required": [ "provider", "country", "query", "page", "count", "reported_total", "next_page", "collected_at", "schema_version", "completeness", "field_notes", "page_size", "next_cursor", "reported_total", "data" ], "properties": { "provider": { "type": "string", "description": "Marketplace ID, like ebay or poshmark." }, "country": { "type": "string", "description": "Always us." }, "query": { "type": "string", "description": "The q you sent, with extra spaces removed." }, "page": { "type": "integer", "description": "The page you asked for." }, "count": { "type": "integer", "description": "Rows in result.data on this page." }, "reported_total": { "type": [ "integer", "null" ], "description": "The total Depop reports, when there is one. Often null after the first page. It doesn't mean full coverage." }, "next_page": { "type": [ "integer", "null" ], "description": "Send this as page to get the next page. Null on the last page." }, "collected_at": { "type": "string", "description": "When we collected the page, as an ISO 8601 timestamp." }, "schema_version": { "type": "integer", "description": "Version of this response shape. Currently 1." }, "completeness": { "type": "string", "description": "Always provider_page_only: one page, not a full sales history." }, "field_notes": { "type": "string", "description": "Plain-text notes on how to read this page's fields." }, "page_size": { "type": "integer", "description": "Rows Depop returned before we removed listings that aren't active US listings priced in USD. It can be larger than count." }, "next_cursor": { "type": [ "string", "null" ], "description": "Send this as cursor, with page=next_page, to get the next page. Null on the last page." }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/DepopListingsRow" } } } }, "DepopListingsJob": { "type": "object", "required": [ "request_id", "status", "credits", "cached" ], "properties": { "request_id": { "type": "string", "description": "ID of this request. Poll it at /v1/jobs/{request_id}." }, "status": { "type": "string", "description": "pending, complete or failed. Always check it, even on HTTP 200.", "enum": [ "pending", "complete", "failed" ] }, "credits": { "type": "integer", "description": "Requests charged: 1 when complete, 0 while pending or when failed." }, "cached": { "type": "boolean", "description": "True when the result came from the 15-minute cache." }, "poll_url": { "type": "string", "description": "Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL." }, "result": { "$ref": "#/components/schemas/DepopListingsPage" }, "error": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string", "enum": [ "schema", "network", "upstream", "throttled", "blocked", "rejected", "auth", "daily_limit", "deadline_exceeded", "credential_storage" ], "description": "Failed job code." } } } } } } } }