> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mindcase.co/llms.txt
> Use this file to discover all available pages before exploring further.

# Etsy Listings API

> Etsy listings with title, URL, price, list price, sale status and currency. Search by keyword or pass search or shop URLs.

`POST /v1/data/etsy/listings/run`

**Pricing:** $0.007 per listing ($7.00 per 1,000).

## Ways to call it

* **Search Keywords**: set `queries` (optional: `maxResults`)
* **Search URLs**: set `searchUrls` (optional: `maxResults`)
* **Shop URLs**: set `shopUrls` (optional: `maxResults`)

## Request

Send the inputs under `params`. Only the keys below are accepted; any other key returns `422 invalid_params`.

**queries** `string[]`

One or more search keywords. One request reads them all.

**searchUrls** `string[]`

One or more search urls. One request reads them all.

Format e.g. `https://www.example.com`.

**shopUrls** `string[]`

One or more shop urls. One request reads them all.

**maxResults** `integer` (default: 100)

How many listings to return in total. Defaults to 100; use 0 for all.

## Example

```bash cURL theme={null}
curl -X POST "https://api.mindcase.co/v1/data/etsy/listings/run?wait=true" \
  -H "Authorization: Bearer $MINDCASE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "params": {
    "queries": [
      "Keramik Tasse handgemacht"
    ],
    "maxResults": 10
  }
}'
```

```python Python theme={null}
import os, requests

r = requests.post(
    "https://api.mindcase.co/v1/data/etsy/listings/run",
    params={"wait": "true"},
    headers={"Authorization": f"Bearer {os.environ['MINDCASE_API_KEY']}"},
    json={"params": {
    "queries": [
        "Keramik Tasse handgemacht"
    ],
    "maxResults": 10
}},
)
job = r.json()
rows = job.get("data", [])  # if job["status"] == "running", poll /v1/jobs/{job_id}/results
```

```javascript Node.js theme={null}
const r = await fetch("https://api.mindcase.co/v1/data/etsy/listings/run?wait=true", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.MINDCASE_API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ params: {
  "queries": [
    "Keramik Tasse handgemacht"
  ],
  "maxResults": 10
} }),
});
const job = await r.json();
const rows = job.data ?? []; // if job.status === "running", poll /v1/jobs/{job_id}/results
```

## Response fields

Each row in `data` is one listing, keyed by these fields.

| Field | Name | Type |
| - | - | - |
| `listingId` | Listing ID | text |
| `title` | Title | text |
| `listingUrl` | Listing URL | url |
| `price` | Price | number |
| `listPrice` | List Price | number |
| `onSale` | On Sale | boolean |
| `currency` | Currency | text |
| `shopName` | Shop Name | text |
| `shopId` | Shop ID | text |
| `shopUrl` | Shop URL | url |
| `rating` | Rating | rating |
| `reviewCount` | Review Count | number |
| `favorites` | Favorites | number |
| `shopRating` | Shop Rating | rating |
| `shopReviewCount` | Shop Review Count | number |
| `shopSalesApprox` | Shop Sales Approx | number |
| `searchRank` | Search Rank | number |
| `sponsored` | Sponsored | boolean |
| `bestseller` | Bestseller | boolean |
| `starSeller` | Star Seller | boolean |
| `freeShipping` | Free Shipping | boolean |
| `isDigital` | Is Digital | boolean |
| `isHandmade` | Is Handmade | boolean |
| `isVintage` | Is Vintage | boolean |
| `isPersonalizable` | Is Personalizable | boolean |
| `boughtLast24h` | Bought Last 24h | number |
| `category` | Category | text |
| `material` | Material | text |
| `shipsFrom` | Ships From | text |
| `listedOn` | Listed On | text |
| `description` | Description | text |
| `mainImage` | Main Image | url |
| `images` | Images | array |
| `variations` | Variations | object\_array |
| `reviewCategoryTags` | Review Category Tags | object\_array |

## Example response

Abridged: long text and lists are shortened.

```json theme={null}
{
  "job_id": "7f3a1c2e-0b9d-4c55-9a51-3f2e8d1b6a40",
  "agent": "etsy/listings",
  "status": "completed",
  "row_count": 1,
  "truncated": false,
  "data": [
    {
      "rating": 5,
      "listingId": "873641303",
      "shopId": "16697722",
      "variations": [
        {
          "number": 0,
          "name": "Primary color",
          "optionCount": 3,
          "options": [
            {
              "id": "1554881177",
              "label": "1) CHESTNUT",
              "rawLabel": "1) CHESTNUT",
              "price": null,
              "priceMin": null,
              "priceMax": null,
              "isPriceRange": null,
              "available": true,
              "imageUrl": "https://i.etsystatic.com/16697722/r/il/566741/2633618964/il_fullxfull.2633618964_68ie.jpg"
            },
            {
              "id": "1554881189",
              "label": "2) CINNAMON",
              "rawLabel": "2) CINNAMON",
              "price": null,
              "priceMin": null,
              "priceMax": null,
              "isPriceRange": null,
              "available": true,
              "imageUrl": "https://i.etsystatic.com/16697722/r/il/895673/2806860835/il_fullxfull.2806860835_6isu.jpg"
            },
            {
              "id": "1538578768",
              "label": "3) CAMEL",
              "rawLabel": "3) CAMEL",
              "price": null,
              "priceMin": null,
              "priceMax": null,
              "isPriceRange": null,
              "available": true,
              "imageUrl": "https://i.etsystatic.com/16697722/r/il/e3ab28/2586127333/il_fullxfull.2586127333_cb5e.jpg"
            }
          ],
          "soldOutOptionCount": 0,
          "hasPrices": false,
          "pricesAreRanges": false
        },
        {
          "number": 1,
          "name": "Personalization",
          "optionCount": 4,
          "options": [
            {
              "id": "1554881179",
              "label": "No Initials",
              "rawLabel": "No Initials ($34.00)",
              "price": 34,
              "priceMin": 34,
              "priceMax": 34,
              "isPriceRange": false,
              "available": true
            },
            {
              "id": "1554881183",
              "label": "up to 3 letters",
              "rawLabel": "up to 3 letters ($36.80)",
              "price": 36.8,
              "priceMin": 36.8,
              "priceMax": 36.8,
              "isPriceRange": false,
              "available": true
            },
            {
              "id": "1554881185",
              "label": "Add Name",
              "rawLabel": "Add Name ($38.80)",
              "price": 38.8,
              "priceMin": 38.8,
              "priceMax": 38.8,
              "isPriceRange": false,
              "available": true
            }
          ],
          "soldOutOptionCount": 0,
          "hasPrices": true,
          "pricesAreRanges": false
        }
      ],
      "shopSalesApprox": 25500,
      "listedOn": "Oct 31, 2026",
      "images": [
        "https://i.etsystatic.com/16697722/r/il/e3ab28/2586127333/il_fullxfull.2586127333_cb5e.jpg",
        "https://i.etsystatic.com/16697722/r/il/2f7466/2586122739/il_fullxfull.2586122739_4du6.jpg"
      ],
      "reviewCount": 582,
      "favorites": 1323,
      "isVintage": null,
      "sponsored": false,
      "shopReviewCount": 6134,
      "mainImage": "https://i.etsystatic.com/16697722/r/il/e3ab28/2586127333/il_300x300.2586127333_cb5e.jpg",
      "shopName": "LoneDeerLeather",
      "reviewCategoryTags": [
        {
          "tag": "Quality",
          "count": 340
        },
        {
          "tag": "Appearance",
          "count": 128
        }
      ],
      "description": "LoneDeer Handmade men's leather wallet Leather, Bi-fold Wallet, Personalized Wallet, Men's Wallet, minimalist wallet, Groomsmen Gift ID: TEXAS005\n\nThis walle...",
      "boughtLast24h": 2,
      "bestseller": null,
      "category": "Bags & Purses < Wallets & Money Clips < Wallets",
      "shopUrl": "https://www.etsy.com/shop/LoneDeerLeather",
      "isDigital": null,
      "starSeller": null,
      "freeShipping": true,
      "onSale": true,
      "material": "Distressed Leather/Waxed Thread/Leather"
    }
  ]
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.