Mercari sold listings API reference

GET /v1/mercari/sold searches one page of Mercari US sold listings by keyword, with condition, price, category and brand filters.

GEThttps://api.soldgraph.com/v1/mercari/sold

Search Mercari US sold listings by keyword. Each call returns one page of up to 100 rows, not a full sales history. Mercari US has no public API of its own. See Mercari API. For a one-page overview, see the Mercari sold listings API page.

displayed_price is the price Mercari shows. It can differ from what the buyer paid, for example after an accepted offer. Rows have no shipping fields, because we can't verify Mercari's shipping amounts.

sold_date_text is the sold time Mercari reports, in UTC. sold_date is its date part. Both can be null. Rows are sold-out listings only. Listings with a sale still in progress are left out.

condition is Mercari's label, like Like New, and condition_id is its number. seller_text is Mercari's seller ID. Rows also have Mercari's category_id and brand_id. There are no brand or size names, because Mercari search doesn't return them.

ParameterTypeDefaultDescription
qstringRequiredSearch keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition.
pageinteger, 1–1001Source page to fetch. Where an endpoint has cursor, pages after 1 also need it.
min_priceinteger, 0–1000000Lowest price, in whole units of the country's currency (US dollars for us). Optional. Must not be more than max_price. You can send it without max_price.
max_priceinteger, 0–1000000Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price.
marketplacemercarimercariOptional. If sent, it must be mercari.
countryususOnly us is supported here. eBay, Vinted, Poshmark, Depop and Whatnot endpoints also take other countries. Mercari, OfferUp, Facebook Marketplace and TCGplayer are US only.
conditionnew, like_new, good, fair or poorOne Mercari condition: new, like_new, good, fair or poor. Rows return Mercari's label and condition_id.
cursorstringThe previous page's next_cursor. Leave it out on page 1. Keep every other parameter the same.
countinteger, 1–100100Most rows per page. Mercari can return fewer.
sortbest_match, newest, price_asc, price_desc, most_popular or recently_soldrecently_soldMercari's result order. newest sorts by when the listing was created. recently_sold sorts by Mercari's sold time.
category_idinteger, 1–2147483647Mercari numeric category ID. Optional.
brand_idinteger, 1–2147483647Mercari numeric brand ID. Optional.
curl -G https://api.soldgraph.com/v1/mercari/sold \  -H "Authorization: Bearer $SOLDGRAPH_KEY" \  --data-urlencode "q=sony headphones" \  -d page=1 \  -d count=25

The first call usually returns 202 and a job to poll. Search jobs covers polling and retries.

#Filters and sorting

  • condition takes one Mercari condition: new, like_new, good, fair or poor.
  • min_price and max_price are whole US dollars. You can send either one alone.
  • category_id and brand_id are Mercari's numeric IDs.
  • count sets the most rows per page, from 1 to 100.
  • sort is recently_sold (default), best_match, newest, price_asc, price_desc or most_popular. recently_sold orders by sold time. newest orders by when the listing was created.

Mercari applies the filters, so reported_total counts only matching listings. Keep the same filters, sort and count on every page.

#Pages and cursors

Start with page=1 and no cursor. For the next page, send page set to next_page and cursor set to next_cursor from the last result.

  • A later page without a cursor, a cursor from a different search, or a cursor in the wrong format returns 422.
  • A cursor Mercari no longer accepts fails the job with error.code rejected. It costs nothing.
  • When next_cursor is null, you're on the last page. You can request at most 100 pages.
  • page_size counts the rows Mercari returned before we removed listings that aren't sold. So count can be smaller.
  • Results are in Mercari's order. reported_total may be capped, and it isn't a full sales history.
  • The same listing can show up on more than one page. Deduplicate by id when you combine pages.

The dashboard Playground has Next page and Start over buttons that handle cursors for you.

Get page 2
curl -G "https://api.soldgraph.com/v1/mercari/sold" \  -H "Authorization: Bearer $SOLDGRAPH_KEY" \  --data-urlencode "q=YOUR SEARCH" \  --data-urlencode "page=2" \  --data-urlencode "cursor=NEXT_CURSOR_FROM_PAGE_1"

#Price summary

summary is plain maths over the rows on the page: how many show a price, the median, the lowest and the highest, plus the oldest and newest sold dates.

  • Sold dates are UTC dates. A row with no sold date is left out of the date range, not out of the prices.
  • Nothing is removed from data. The summary counts rows; it never filters them.
  • It covers one page. Page through to cover more.

#Example response

Response
{  "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": 2,    "completeness": "provider_page_only",    "summary": {      "priced_count": 1,      "currency": "USD",      "median": 35,      "low": 35,      "high": 35,      "p25": 35,      "p75": 35,      "earliest_sold_date": "2026-09-28",      "latest_sold_date": "2026-09-28"    },    "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",        "sold_date": "2026-09-28",        "sold_date_text": "2026-09-28T12:00:00+00:00",        "condition": "Good",        "seller_text": "123456789",        "image": null,        "condition_id": 3,        "brand_id": 1,        "category_id": 1594      }    ],    "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, without labels. Reported totals may be capped. Results cover one source page only.",    "next_cursor": null  }}
FieldTypeDescription
request_idstringID of this request. Poll it at /v1/jobs/{request_id}.
statusstringpending, complete or failed. Always check it, even on HTTP 200.
creditsintegerRequests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed.
cachedbooleanTrue when the result came from the 15-minute cache.
poll_urlstringOnly while pending. A path like /v1/jobs/{id}: join it to https://api.soldgraph.com, not to the /v1 base URL.
error.codestringOnly when failed. See failed job codes.
error.messagestringOnly when failed. What the code means, in plain words.
resultobjectOnly when complete. One source page from the marketplace.
result.providerstringMarketplace ID, like ebay or poshmark.
result.countrystringThe country searched: us, or on eBay the country you sent.
result.querystringThe q you sent, with extra spaces removed.
result.pageintegerThe page you asked for.
result.countintegerRows in result.data on this page.
result.reported_totalintegerTotal matches the marketplace reports for the search. It may be rounded or capped.
result.next_pageinteger | nullSend this as page to get the next page. Null on the last page, and on page 100, the deepest page served.
result.collected_atstringWhen we collected the page, as an ISO 8601 timestamp.
result.schema_versionintegerVersion of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning.
result.completenessstringprovider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only.
result.field_notesstringPlain-text notes on how to read this page's fields.
result.page_sizeintegerRows Mercari returned before we removed listings that aren't sold. It can be larger than count.
result.summaryobjectPrice 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.
result.next_cursorstring | nullSend this as cursor, with page=next_page, to get the next page. Null on the last page.
result.data[].idstringThe marketplace's listing ID.
result.data[].titlestring | nullListing title as shown.
result.data[].linkstringURL of the listing on the marketplace.
result.data[].displayed_priceobject{ amount, currency } of the price Mercari shows. It can differ from what the buyer paid.
result.data[].displayed_price_textstring | nullThe price text as shown, like $189.00.
result.data[].sold_datestring | nullThe date part of sold_date_text, as YYYY-MM-DD. Null when Mercari doesn't report a sold time.
result.data[].sold_date_textstring | nullThe sold time Mercari reports, as a UTC timestamp. Null when Mercari doesn't report one.
result.data[].conditionstring | nullMercari's condition label: New, Like New, Good, Fair or Poor.
result.data[].seller_textstring | nullThe seller's Mercari ID, as a string.
result.data[].imagestring | nullImage URL on Mercari's image CDN.
result.data[].condition_idinteger | nullMercari's condition number: 1 new, 2 like new, 3 good, 4 fair, 5 poor.
result.data[].category_idinteger | nullMercari's category ID for the listing.
result.data[].brand_idinteger | nullMercari's brand ID. The brand name isn't returned.
Try it
Request
curl -G https://api.soldgraph.com/v1/mercari/sold \  -H "Authorization: Bearer $SOLDGRAPH_KEY" \  --data-urlencode "q=sony headphones" \  -d count=25
Sign in to runFree account, no card.

Overviews: eBay sold listings API · findCompletedItems alternative · Poshmark sold listings API · Mercari sold listings API · Pokémon card price API · Sold comps API for reseller apps