--- title: "Mercari sold listings" method: GET path: "/mercari/sold" tags: ["Mercari"] --- # Mercari sold listings `GET /mercari/sold` ## Request - Base URL: `https://api.soldgraph.com/v1` - URL: `https://api.soldgraph.com/v1/mercari/sold` - Auth: HTTP bearer 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. ## Query parameters - `q` string, required - `page` integer - `min_price` integer - `max_price` integer - `marketplace` 'mercari' - `country` 'us' - `condition` 'new' | 'like_new' | 'good' | 'fair' | 'poor' - `cursor` string - `count` integer - `sort` 'best_match' | 'newest' | 'price_asc' | 'price_desc' | 'most_popular' | 'recently_sold' - `category_id` integer - `brand_id` integer ## Headers - `Idempotency-Key` string ## Response `200` Complete, including cache hits. Costs 1 request. - MercariSoldJob - `request_id` string, required: ID of this request. Poll it at /v1/jobs/{request_id}. - `status` 'pending' | 'complete' | 'failed', required: pending, complete or failed. Always check it, even on HTTP 200. - `credits` integer, required: Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. - `cached` boolean, required: True when the result came from the 15-minute cache. - `poll_url` string: Only while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL. - `result` MercariSoldPage - `provider` string, required: Marketplace ID, like ebay or poshmark. - `country` string, required: The country searched: us, or on eBay the country you sent. - `query` string, required: The q you sent, with extra spaces removed. - `page` integer, required: The page you asked for. - `count` integer, required: Rows in result.data on this page. - `reported_total` integer, required: Total matches the marketplace reports for the search. It may be rounded or capped. - `next_page` integer, nullable, required: Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served. - `collected_at` string, required: When we collected the page, as an ISO 8601 timestamp. - `schema_version` integer, required: Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning. - `completeness` string, required: provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only. - `field_notes` string, required: Plain-text notes on how to read this page's fields. - `page_size` integer, required: Rows Mercari returned before we removed listings that aren't sold. It can be larger than count. - `summary` object, required: Price maths over the rows on this page: priced_count, currency, median, low, high, p25, p75, earliest_sold_date and latest_sold_date. No row is removed from data. Rows with no single readable price are left out of the maths. - `priced_count` integer, required: Rows on this page that show one price. - `currency` string, required: Currency of the amounts below. - `median` number, nullable, required: Middle displayed price of those rows. - `low` number, nullable, required: Lowest displayed price. - `high` number, nullable, required: Highest displayed price. - `earliest_sold_date` string, nullable, required: Oldest sold date on this page. - `latest_sold_date` string, nullable, required: Newest sold date on this page. - `p25` number, nullable, required: First-quartile displayed price: a quarter of priced rows are at or below it. - `p75` number, nullable, required: Third-quartile displayed price. With `p25`, a range that ignores a stray accessory or parts listing. - `next_cursor` string, nullable, required: Send this as cursor, with page=next_page, to get the next page. Null on the last page. - `data` MercariSoldRow[], required - `id` string, required: The marketplace's listing ID. - `title` string, nullable, required: Listing title as shown. - `link` string, required: URL of the listing on the marketplace. - `displayed_price` Money, required - `amount` number, required - `currency` string, required: ISO 4217 code, like USD. - `displayed_price_text` string, nullable, required: The price text as shown, like $189.00. - `sold_date` string, nullable, required: The date part of sold_date_text, as YYYY-MM-DD. Null when Mercari doesn't report a sold time. - `sold_date_text` string, nullable, required: The sold time Mercari reports, as a UTC timestamp. Null when Mercari doesn't report one. - `condition` string, nullable, required: Mercari's condition label: New, Like New, Good, Fair or Poor. - `seller_text` string, nullable, required: The seller's Mercari ID, as a string. - `image` string, nullable, required: Image URL on Mercari's image CDN. - `condition_id` integer, nullable, required: Mercari's condition number: 1 new, 2 like new, 3 good, 4 fair, 5 poor. - `category_id` integer, nullable, required: Mercari's category ID for the listing. - `brand_id` integer, nullable, required: Mercari's brand ID. The brand name isn't returned. - `error` object - `code` 'page_mismatch' | 'schema' | 'network' | 'upstream' | 'throttled' | 'blocked' | 'rejected' | 'not_found' | 'filter_not_supported' | 'filter_not_applied' | 'location_not_served' | 'auth' | 'daily_limit' | 'deadline_exceeded' | 'credential_storage', required: Failed job code. - `message` string: What the code means, in plain words. ## Other responses - `202`: Pending. Poll `poll_url` (or `Location`) with the same API key. Both are paths: join them to https://api.soldgraph.com. - `401`: invalid_api_key: The API key is missing, malformed or revoked. - `403`: account_suspended: The account is suspended, so none of its keys work. Email support to restore it. origin_not_allowed: A browser sent the request from a site that isn't allowed. Call the API from your server. - `404`: not_found: No such path. request_not_found: The job ID is well-formed but unknown, or belongs to another account. An ID that isn't a UUID is no such path: 404 not_found. batch_not_found: No batch with that ID belongs to this account. Or a replay of a search that failed because of the search (the body is then the failed job): not_found. - `405`: method_not_allowed: Wrong method for this route. Searches, jobs and usage use GET. Only /v1/batches takes POST. - `409`: idempotency_conflict: This Idempotency-Key was already used with different search parameters. result_not_ready: CSV was requested before every search settled. Poll as JSON until status is complete, then ask for CSV. - `413`: payload_too_large: The batch body is over 256 KB. - `414`: uri_too_long: The query string is longer than 2,048 characters. - `415`: unsupported_media_type: A batch must be sent as Content-Type: application/json. - `422`: unsupported_or_invalid_query: An unknown parameter, or a value outside the documented range. error.param names the input to fix when it is one of the route's inputs. duplicate_parameter: A parameter was sent more than once. sort_not_implemented: sort=best_deal is not available. invalid_idempotency_key: Idempotency-Key must be 1–128 printable ASCII characters, with no spaces. invalid_wait: wait must be a whole number from 0 to 20. invalid_body: The batch body is not JSON, or has no searches list. batch_too_large: The batch holds more searches than your plan allows at once. pages counts as one search per page. invalid_format: format must be json or csv, and include must be results. Or a replay of a search that failed because of the search (the body is then the failed job): rejected, filter_not_supported, filter_not_applied, location_not_served. - `429`: rate_limited: More than 60 API calls this minute for your account. quota_exceeded: Your plan's allowance is used up, and you have no extra requests left. too_many_pending: Your account has too many searches still pending. Wait for results before sending more. - `503`: Temporary failure, or a replay of a failed search (the body is then the failed job). upstream_daily_limit: The marketplace's daily limit was reached, so new searches are paused. Cached results still work. queue_full: The collection queue is full. collection_unavailable: We can't collect from this marketplace right now. storage_unavailable: Our database is briefly unavailable. origin_unavailable: The edge couldn't reach our API server. service_unconfigured: The API is misconfigured on our side. Contact support. --- [API](https://skmtc.dev/soldgraph/apis/soldgraph-api.md) · [All operations](https://skmtc.dev/soldgraph/apis/soldgraph-api/llms.txt) · [OpenAPI document](https://skmtc.dev/soldgraph/apis/soldgraph-api/revisions/137f0810f983?raw)