# Mercari API: Search listings

> Searches Mercari US listings for items for sale or sold, with condition, price and sorting filters, and adds seller, size and shipping details from each item page. Sold prices are displayed listing prices.

Unofficial. Not affiliated with or endorsed by Mercari.

- Page: https://fous.com/methods/mercari.com/search-listings
- Method: `mercari.com/search_listings`, version 1
- Website: mercari.com
- Returns: title, price, condition, brand, size, sold, seller name and rating, free shipping, image, link, item id
- Effect: read (it gets data and changes nothing)
- Sign-in: none needed
- Cost: 1 credit per completed run (1¢ with pay as you go); failed runs are free
- Verified: Nov 2, 2026

## Inputs

| Field | Type | Required | In the run below | Description |
|---|---|---|---|---|
| `sort` | string | no | `"price_low_to_high"` | Results order, such as newest. One of "best_match", "newest", "price_low_to_high", "price_high_to_low". Default "best_match". |
| `query` | string | yes | `"Coach purse"` | Words to search for, such as Nintendo Switch OLED. |
| `condition` | string | no | `"good"` | Item condition, such as good. One of "any", "new", "like_new", "good", "fair", "poor". Default "any". |
| `max_price` | number | no | `200` | Highest item price in USD, such as 200. |
| `min_price` | number | no | `20` | Lowest item price in USD, such as 50. |
| `sold_only` | boolean | no | `true` | Show only sold listings, such as true. Default false. |
| `max_results` | integer | no | `6` | Maximum listings to return, such as 30 (up to 120). Default 30. |

## Output

From a run on Oct 31, 2026, shortened. Its input:

```json
{
  "sort": "price_low_to_high",
  "query": "Coach purse",
  "condition": "good",
  "max_price": 200,
  "min_price": 20,
  "sold_only": true,
  "max_results": 6
}
```

Its output:

```json
{
  "listings": [
    {
      "size": null,
      "sold": true,
      "brand": "Coach",
      "price": 20,
      "title": "Coach multi colored purse",
      "item_id": "m87446295908",
      "currency": "USD",
      "condition": "Good",
      "image_link": "https://u-mercari-images.mercdn.net/photos/m87446295908_1.jpg?1740096780",
      "seller_name": "Lupita's Chancla",
      "listing_link": "https://www.mercari.com/us/item/m87446295908/",
      "free_shipping": false,
      "seller_rating": 5
    },
    {
      "size": null,
      "sold": true,
      "brand": "Coach",
      "price": 20,
      "title": "Coach Leather purse",
      "item_id": "m85070668676",
      "currency": "USD",
      "condition": "Good",
      "image_link": "https://u-mercari-images.mercdn.net/photos/m85070668676_1.jpg?1740096939",
      "seller_name": "Lupita's Chancla",
      "listing_link": "https://www.mercari.com/us/item/m85070668676/",
      "free_shipping": false,
      "seller_rating": 5
    },
    {
      "size": null,
      "sold": true,
      "brand": "Coach",
      "price": 20,
      "title": "Coach grey purse",
      "item_id": "m29393594445",
      "currency": "USD",
      "condition": "Good",
      "image_link": "https://u-mercari-images.mercdn.net/photos/m29393594445_1.jpg?1740096082",
      "seller_name": "Lupita's Chancla",
      "listing_link": "https://www.mercari.com/us/item/m29393594445/",
      "free_shipping": false,
      "seller_rating": 5
    }
  ]
}
```

## Run it

From code, with a Fous API key in `FOUS_API_KEY`; the answer's `data` holds the output:

```bash
curl https://api.fous.com/v1/runs \
  -H "Authorization: Bearer $FOUS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"method":"mercari.com/search_listings","input":{"sort":"price_low_to_high","query":"Coach purse","condition":"good","max_price":200,"min_price":20,"sold_only":true,"max_results":6}}'
```

From an AI agent connected to the Fous MCP server: its `run` with the same method and input. To connect one, give it `set up https://fous.com/SKILL.md`.

## Ask your agent

- Find sold Mercari listings for Lululemon Align leggings so I can see what they actually went for
- What are the cheapest like-new AirPods Pro 2 for sale right now under $150? Sort lowest price first.
- Show me the newest listings for vintage Pyrex bowls between $20 and $80, include seller ratings and whether shipping is free
- On mercari.com, pull up to 60 sold Pokemon Charizard cards in good condition, highest price first
- I'm looking for a used Canon AE-1 film camera, any condition, max $250. List title, price, seller and link.

## Input schema

```json
{
  "type": "object",
  "required": [
    "query"
  ],
  "properties": {
    "sort": {
      "enum": [
        "best_match",
        "newest",
        "price_low_to_high",
        "price_high_to_low"
      ],
      "type": "string",
      "default": "best_match",
      "description": "Results order, such as newest."
    },
    "query": {
      "type": "string",
      "minLength": 1,
      "description": "Words to search for, such as Nintendo Switch OLED."
    },
    "condition": {
      "enum": [
        "any",
        "new",
        "like_new",
        "good",
        "fair",
        "poor"
      ],
      "type": "string",
      "default": "any",
      "description": "Item condition, such as good."
    },
    "max_price": {
      "type": "number",
      "minimum": 0,
      "description": "Highest item price in USD, such as 200."
    },
    "min_price": {
      "type": "number",
      "minimum": 0,
      "description": "Lowest item price in USD, such as 50."
    },
    "sold_only": {
      "type": "boolean",
      "default": false,
      "description": "Show only sold listings, such as true."
    },
    "max_results": {
      "type": "integer",
      "default": 30,
      "maximum": 120,
      "minimum": 1,
      "description": "Maximum listings to return, such as 30 (up to 120)."
    }
  }
}
```

## Output schema

```json
{
  "type": "object",
  "required": [
    "listings"
  ],
  "properties": {
    "listings": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "title",
          "price",
          "currency",
          "condition",
          "brand",
          "size",
          "sold",
          "seller_name",
          "seller_rating",
          "free_shipping",
          "image_link",
          "listing_link",
          "item_id"
        ],
        "properties": {
          "size": {
            "type": [
              "string",
              "null"
            ]
          },
          "sold": {
            "type": "boolean"
          },
          "brand": {
            "type": [
              "string",
              "null"
            ]
          },
          "price": {
            "type": "number",
            "description": "USD price."
          },
          "title": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "condition": {
            "type": [
              "string",
              "null"
            ]
          },
          "image_link": {
            "type": [
              "string",
              "null"
            ]
          },
          "seller_name": {
            "type": [
              "string",
              "null"
            ]
          },
          "listing_link": {
            "type": "string"
          },
          "free_shipping": {
            "type": [
              "boolean",
              "null"
            ]
          },
          "seller_rating": {
            "type": [
              "number",
              "null"
            ],
            "description": "Average rating out of five."
          }
        }
      }
    }
  }
}
```

## See more

- [OfferUp API: Search listings](https://fous.com/methods/offerup.com/search-listings.md): Finds OfferUp items for sale near a US city or ZIP code, with prices, condition, seller names, distance and links. Distances use approximate listing locations.
- [Macy's API: Search products](https://fous.com/methods/macys.com/search-products.md): Searches Macy's products in the site's order with optional USD price bounds, sale-only results and sorting. Prices for products with a range use the lowest shown price.
- [AliExpress API: Search products](https://fous.com/methods/aliexpress.com/search-products.md): Searches AliExpress listings by product words, shipping destination, price range and sort order. Unpriced promotional cards are omitted; free shipping is marked only when the listing explicitly says so.
- [Vinted API: Search listings](https://fous.com/methods/vinted.com/search-listings.md): Searches public Vinted listings in one country with brand, size, condition, price and sorting filters. Returns up to 96 available items with seller usernames when the public profile is available.
- [Rakuten API: Search products](https://fous.com/methods/rakuten.co.jp/search-products.md): Searches Rakuten Ichiba products by keyword, price range, free shipping and sort order. Returns up to 45 regular listings in the order shown; sponsored placements are excluded. Prices are listed starting prices when an item has variants.
- [Nordstrom API: Search products](https://fous.com/methods/nordstrom.com/search-products.md): Search Nordstrom products by words, price, sale status and sort order. Prices are the lowest listed price. Available sizes may be empty when a product page is unavailable.
- [Best Buy API: Search products](https://fous.com/methods/bestbuy.com/search-products.md): Searches Best Buy US products with an optional price range, sort order and page. Prices and availability come from public listings and may vary by location.
- [CarMax API: Search used cars](https://fous.com/methods/carmax.com/search-cars.md): Searches CarMax used cars by make and model with optional ZIP, distance, year, price and mileage filters, keeping CarMax's order. Pages expose only the first 48 cars; distance is CarMax's distance from the selected local store, and larger limits or narrow distance filters may return fewer matches.