# Mercari Listing Search API Documentation

<p><strong>Mercari Listing Search API Documentation</strong> Search Mercari by keyword in the US market (USD) or the Japanese market (JPY). Filter by brand, category, condition, size, price range, shipping payer, seller and status. Set status to sold to read sold prices. Each listing has id, url, title, price as a number with currency, condition, brand, size, photos, likes, status and times; the Japanese market adds listing_type (c2c or shop). Sort by relevance, price or newest. The page parameter pages 30 listings at a time: up to page 33 in the US and page 500 in Japan. The total is capped at 10000 (US) and 15000 (JP). Ids for brand, category and size come from the listings. The data is public and read only. Each successful request costs 1 credit. A failed request is never billed.</p>

- **Documentation:** [https://scrappa.co/docs/mercari-api/mercari_search](https://scrappa.co/docs/mercari-api/mercari_search)
- **API group:** Mercari API
- **Endpoint:** `GET https://scrappa.co/api/mercari/search`

## Authentication

Send your Scrappa API key in the `X-API-KEY` request header. Paid endpoints also support accountless x402 payments when called without an API key.

## Parameters

| Parameter | Type | Required | Description |
| --- | --- | --- | --- |
| `query` | string | No | Search keywords, for example nike. Required unless you send category, brand or seller. |
| `market` | string | No | Marketplace: us (United States) or jp (Japan). Defaults to us. The two markets are separate: ids and filters differ. |
| `category` | string | No | Comma list of Mercari category ids, for example 308. Take ids from the category block of search results. |
| `brand` | string | No | Comma list of Mercari brand ids, for example 4578 (US Nike) or 857 (JP NIKE). Take ids from search results. |
| `condition` | string | No | Comma list of condition ids. US: 1 New, 2 Like new, 3 Good, 4 Fair, 5 Poor. JP adds 6 Bad. |
| `size` | string | No | Comma list of size ids, taken from the size block of search results. |
| `color` | string | No | Comma list of color ids. Japan market only. |
| `min_price` | number | No | Lowest price in the market currency: US dollars or Japanese yen. |
| `max_price` | number | No | Highest price in the market currency. Must be at least min_price. |
| `status` | string | No | on_sale (default) or sold. Sold listings carry the sold price. |
| `sort` | string | No | relevance (default), price_asc, price_desc or newest. |
| `shipping_payer` | string | No | buyer or seller: who pays for shipping. |
| `seller` | integer | No | Numeric seller id. Returns only listings of that seller. |
| `page` | integer | No | Page number, 30 listings per page. Defaults to 1. Maximum 33 for us and 500 for jp. |

## Example response

```json
{
    "data": {
        "page": 1,
        "items": [
            {
                "id": "m85764352496",
                "url": "https://www.mercari.com/us/item/m85764352496/",
                "size": {
                    "id": 78,
                    "name": "13 (46)"
                },
                "brand": {
                    "id": 31861,
                    "name": "Nike SB"
                },
                "likes": 7,
                "price": 250,
                "title": "Freddy Krueger SB Dunks",
                "market": "us",
                "photos": [
                    "https://u-mercari-images.mercdn.net/photos/m85764352496_1.jpg?1793310628"
                ],
                "seller": {
                    "id": 207052431,
                    "name": null,
                    "rating_count": 81
                },
                "status": "on_sale",
                "category": {
                    "id": 399,
                    "name": "Fashion sneakers"
                },
                "currency": "USD",
                "condition": {
                    "id": 1,
                    "name": "New"
                },
                "listed_at": "2026-10-29T21:50:28Z",
                "thumbnail": "https://u-mercari-images.mercdn.net/photos/m85764352496_1.jpg?1793310628",
                "sold_price": null,
                "updated_at": "2026-10-29T21:50:28Z",
                "original_price": null,
                "discount_percent": null
            }
        ],
        "query": "nike",
        "total": 10000,
        "market": "us",
        "has_next": true,
        "per_page": 30,
        "total_is_capped": true
    },
    "success": true
}
```

## Errors

| Status | Error | Description |
| --- | --- | --- |
| 422 | Validation Error | A parameter is missing or invalid. Mercari is not called and the request is not billable. |
| 503 | Transport Unavailable | Mercari did not answer after several tries. Retry later. This response is not billable. |

## More Scrappa resources

- [API documentation](https://scrappa.co/docs)
- [Full LLM-readable API reference](https://scrappa.co/llms-full.txt)
- [OpenAPI specification](https://scrappa.co/docs/api.json)
- [Pricing](https://scrappa.co/pricing)