Mercari active listings
GET /v1/mercari/listings searches one page of Mercari US active listings by keyword, with condition, price, category and brand filters.
https://api.soldgraph.com/v1/mercari/listingsSearch Mercari US listings that are for sale now. Each call returns one page of up to 100 rows, in the order you pick with sort.
displayed_price is the price Mercari shows. listed_at is when the listing was created. Rows have no shipping fields, because we can't verify Mercari's shipping amounts. Every listing is a fixed price, with no bids or end times.
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. Listings with a sale in progress are left out.
| Parameter | Type | Default | Description |
|---|---|---|---|
q | string | Required | Search keywords, 1–200 characters, as you'd type them into the marketplace's search box. Be specific: model, size, grade, edition. |
page | integer, 1–100 | 1 | Source page to fetch. Where an endpoint has cursor, pages after 1 also need it. |
min_price | integer, 0–1000000 | Lowest 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_price | integer, 0–1000000 | Highest price, in whole units of the country's currency (US dollars for us). Optional. You can send it without min_price. | |
marketplace | mercari | mercari | Optional. If sent, it must be mercari. |
country | us | us | Only us is supported here. eBay, Vinted, Poshmark, Depop and Whatnot endpoints also take other countries. Mercari, OfferUp, Facebook Marketplace and TCGplayer are US only. |
condition | new, like_new, good, fair or poor | One Mercari condition: new, like_new, good, fair or poor. Rows return Mercari's label and condition_id. | |
cursor | string | The previous page's next_cursor. Leave it out on page 1. Keep every other parameter the same. | |
count | integer, 1–100 | 100 | Most rows per page. Mercari can return fewer. |
sort | best_match, newest, price_asc, price_desc or most_popular | best_match | Mercari's result order. newest sorts by when the listing was created. |
category_id | integer, 1–2147483647 | Mercari numeric category ID. Optional. | |
brand_id | integer, 1–2147483647 | Mercari numeric brand ID. Optional. |
curl -G https://api.soldgraph.com/v1/mercari/listings \ -H "Authorization: Bearer $SOLDGRAPH_KEY" \ --data-urlencode "q=sony headphones" \ -d page=1 \ -d count=25The first call usually returns 202 and a job to poll. Search jobs covers polling and retries.
#Filters and sorting
conditiontakes one Mercari condition:new,like_new,good,fairorpoor.min_priceandmax_priceare whole US dollars. You can send either one alone.category_idandbrand_idare Mercari's numeric IDs.countsets the most rows per page, from 1 to 100.sortisbest_match(default),newest,price_asc,price_descormost_popular.newestorders 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.coderejected. It costs nothing. - When
next_cursoris null, you're on the last page. You can request at most 100 pages. page_sizecounts the rows Mercari returned before we removed listings that aren't for sale. Socountcan be smaller.- Results are in the order you pick with
sort.reported_totalmay be capped. - The same listing can show up on more than one page. Deduplicate by
idwhen you combine pages.
The dashboard Playground has Next page and Start over buttons that handle cursors for you.
curl -G "https://api.soldgraph.com/v1/mercari/listings" \ -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 asking price, the lowest and the highest.
- Nothing is removed from
data. The summary counts rows; it never filters them. - It covers one page. Page through to cover more.
#Example 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": 42, "low": 42, "high": 42, "p25": 42, "p75": 42 }, "data": [ { "id": "m00000000001", "title": "Illustrative Sony headphones listing", "link": "https://www.mercari.com/us/item/m00000000001/", "displayed_price": { "amount": 42, "currency": "USD" }, "displayed_price_text": "$42.00", "condition": "Good", "listed_at": "2026-09-27T10:04:12-07:00", "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 }}| Field | Type | Description |
|---|---|---|
request_id | string | ID of this request. Poll it at /v1/jobs/{request_id}. |
status | string | pending, complete or failed. Always check it, even on HTTP 200. |
credits | integer | Requests charged: 1 when complete, 0 for a page past the last one, while pending, or when failed. |
cached | boolean | 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. |
error.code | string | Only when failed. See failed job codes. |
error.message | string | Only when failed. What the code means, in plain words. |
result | object | Only when complete. One source page from the marketplace. |
result.provider | string | Marketplace ID, like ebay or poshmark. |
result.country | string | The country searched: us, or on eBay the country you sent. |
result.query | string | The q you sent, with extra spaces removed. |
result.page | integer | The page you asked for. |
result.count | integer | Rows in result.data on this page. |
result.reported_total | integer | Total matches the marketplace reports for the search. It may be rounded or capped. |
result.next_page | integer | null | Send this as page to get the next page. Null on the last page, and on page 100, the deepest page served. |
result.collected_at | string | When we collected the page, as an ISO 8601 timestamp. |
result.schema_version | integer | Version of the result's shape for that marketplace: 1 or 2. It only rises when a field changes meaning. |
result.completeness | string | provider_page_only: one page as the marketplace served it, not a full history. TCGplayer recent sales say recent_sample_only. |
result.field_notes | string | Plain-text notes on how to read this page's fields. |
result.page_size | integer | Rows Mercari returned before we removed listings that aren't for sale. It can be larger than count. |
result.summary | object | Price maths over the rows on this page: priced_count, currency, median, low, high. No row is removed from data. Rows with no single readable price are left out of the maths. |
result.next_cursor | string | null | Send this as cursor, with page=next_page, to get the next page. Null on the last page. |
result.data[].id | string | The marketplace's listing ID. |
result.data[].title | string | null | Listing title as shown. |
result.data[].link | string | URL of the listing on the marketplace. |
result.data[].displayed_price | object | { amount, currency } of the price Mercari shows. |
result.data[].displayed_price_text | string | null | The price text, like $35.00. |
result.data[].condition | string | null | Mercari's condition label: New, Like New, Good, Fair or Poor. |
result.data[].listed_at | string | null | When the listing was published, as an ISO 8601 timestamp. |
result.data[].seller_text | string | null | The seller's Mercari ID, as a string. |
result.data[].image | string | null | Image URL on Mercari's image CDN. |
result.data[].condition_id | integer | null | Mercari's condition number: 1 new, 2 like new, 3 good, 4 fair, 5 poor. |
result.data[].category_id | integer | null | Mercari's category ID for the listing. |
result.data[].brand_id | integer | null | Mercari's brand ID. The brand name isn't returned. |
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