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

# Products and shops

> MCP tools to search and open Etsy products and shops, their reviews, tags and sales history

These tools search and open Etsy products (listings) and shops. They all need the **Search and read Etsy market research** permission (`research:read`) and only read: nothing changes in Alura or on Etsy.

## Try these prompts

Claude and GPT picked the tools shown for these prompts in Alura's evaluation runs. Replace the parts in brackets with your own.

| Ask your assistant | Tools it uses |
| - | - |
| What are the best-selling personalized tumblers on Etsy? Give me the top 3 with their estimated monthly sales. | `search_products` |
| Find the best-selling products in the Necklaces category that cost under \$50. | `browse_categories`, then `search_products` |
| Compare Etsy listings \[ID], \[ID] and \[ID] on estimated monthly sales. Which sells best? | `get_products` |
| Find products similar to Etsy listing \[ID] so I can size up its competition. | `find_similar_products` |
| What can you tell me about \[Etsy listing or shop link]? | `lookup_etsy_url` |
| Which tags does Etsy listing \[ID] use, and which of them has the highest search volume? | `get_product_tags` |
| Find Etsy shops that sell crochet patterns and have lots of sales. | `search_shops` |
| What are the best-selling products of Etsy shop \[shop ID]? | `get_shop` |
| What do customers complain about in the reviews of Etsy shop \[shop ID]? Focus on the lower ratings. | `get_reviews` |
| Show me the month-by-month estimated sales of Etsy listing \[ID]. | `get_sales_history` |

## Good to know

* **Estimates.** Sales and revenue figures are estimates. [Sales estimates](/methodology/sales-estimates) explains how Alura makes them and where they're weak.
* **Sales history** needs the Growth plan or above. On other plans the call is refused before anything is charged.
* **Known items only, for now.** A product or shop Alura hasn't seen answers `fetch_unavailable`, free. See [pending items](/mcp/troubleshooting#pending-items).
* **Mature listings** are left out over MCP. See [Mature listings](/mcp/tools#mature-listings).
* **Links.** `lookup_etsy_url` reads the link's shop or listing ID or shop name. It never opens the link.

## Tools

### `search_products`

**Search Etsy products.** Search Etsy products (other sellers' listings) in Alura's research data: filter by words, category, USD price, estimated lifetime or monthly sales, reviews, listing date, who made it, when it was made, digital or physical, personalization, free shipping and shop country; sort by relevance, estimated sales, estimated monthly sales, estimated revenue, price, newest, reviews or listing score. Returns up to 50 product summaries per page with estimated sales and revenue; pass `next_cursor` back as `cursor` for the next page of the same search. Use get\_products for a product's full profile.

* **Cost of `search_products`:** 10 API credits per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/products`](/api-reference/research/products/search).

| Argument | Type | Required | Description |
| - | - | - | - |
| `q` | string | No | Words that must all appear in the product, for example "personalized mug". |
| `category_id` | string | No | An Etsy category ID from browse\_categories; includes every category under it. |
| `price_min` | number | No | Lowest price in USD. |
| `price_max` | number | No | Highest price in USD. |
| `est_sales_min` | integer | No | Fewest estimated lifetime sales. |
| `est_sales_max` | integer | No | Most estimated lifetime sales. |
| `est_monthly_sales_min` | integer | No | Fewest estimated sales per month. |
| `est_monthly_sales_max` | integer | No | Most estimated sales per month. |
| `reviews_min` | integer | No | Fewest reviews. |
| `listed_after` | string | No | Listed at or after this date, YYYY-MM-DD. |
| `listed_before` | string | No | Listed at or before this date, YYYY-MM-DD. |
| `who_made` | `i_did`, `someone_else`, `collective` | No | |
| `when_made` | `made_to_order`, `2020_2025`, `2020_2024`, `2020_2023`, `2010_2019`, `2006_2009`, `2000_2005`, `before_2006`, `1990s`, `1980s`, `1970s`, `1960s`, `1950s`, `1940s`, `1930s`, `1920s`, `1910s`, `1900s`, `1800s`, `1700s`, `before_1700` | No | |
| `is_digital` | boolean | No | true: digital downloads only; false: physical products only. |
| `is_personalizable` | boolean | No | |
| `free_shipping` | boolean | No | |
| `shop_country` | string | No | The shop's two-letter country code, for example US. |
| `sort` | `relevance`, `est_sales`, `est_monthly_sales`, `est_revenue`, `price`, `newest`, `reviews`, `listing_score` | No | relevance (default) or a field; a field sort leaves out products where that value is unknown. |
| `order` | `asc`, `desc` | No | desc (default) or asc; only with a field sort. |
| `cursor` | string | No | next\_cursor from the previous page of the same search. |
| `limit` | integer | No | Results per page, 1-50 (default 20). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "q": "mug",
  "price_max": 30,
  "sort": "est_sales"
}
```

### `get_products`

**Get Etsy products.** Get Etsy products (other sellers' listings) by listing ID. One ID returns the full research profile: price, category, tags, attributes, reviews, Alura's estimated sales and revenue (lifetime, monthly average, last month, 3-month trend), listing score and when the data was last updated. 2 to 30 IDs return a summary of each (price, category, reviews, estimated sales and revenue, listing score); IDs Alura does not have come back in `unfetched` (with a code and `retry_after` seconds) or `not_found`, free. Use it after a search or when the user names listings.

* **Cost of `get_products`:** 1 API credit per call, or 1 API credit per item returned.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/products/{id}`](/api-reference/research/products/get), [`GET /v1/research/products`](/api-reference/research/products/getMany).

| Argument | Type | Required | Description |
| - | - | - | - |
| `ids` | string\[] | Yes | Etsy listing IDs as strings, for example \["4524717183"]; 1 to 30 per call. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "ids": [
    "4524717183"
  ]
}
```

### `find_similar_products`

**Find similar products.** Find Etsy products (other sellers' listings) similar to one product, by listing ID: products sharing its title words and tags, ranked higher in the same category. Returns up to 50 product summaries per page with estimated sales and revenue, best match first, never the product itself; pass `next_cursor` back as `cursor` for the next page. Use it to map a product's competition after search\_products or get\_products; a product Alura does not have is not found.

* **Cost of `find_similar_products`:** 10 API credits per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/products/{id}/similar`](/api-reference/research/products/similar).

| Argument | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | The Etsy listing ID to find similar products for, as a string, for example "4524717183". |
| `cursor` | string | No | next\_cursor from the previous page for the same product. |
| `limit` | integer | No | Results per page, 1-50 (default 20). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "id": "4524717183"
}
```

### `get_product_tags`

**Get a product's tags.** Get the seller's tags on an Etsy product (another seller's listing) by its listing ID, each matched to Alura's keyword metrics in the listing's language: estimated monthly Etsy searches, competition level and 3-month trend. Use it to judge which of a competitor's tags are worth targeting. A tag Alura has no keyword for has `keyword: null`.

* **Cost of `get_product_tags`:** 1 API credit per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/products/{id}/tags`](/api-reference/research/products/tags).

| Argument | Type | Required | Description |
| - | - | - | - |
| `product_id` | string | Yes | Etsy listing ID as a string, for example "4524717183". |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "product_id": "4524717183"
}
```

### `lookup_etsy_url`

**Look up an Etsy URL.** Look up the Etsy shop or product (another seller's) an Etsy URL points to, or an Etsy shop by its exact name, and get its full research profile, as get\_shop or get\_products return it. Takes `url` ([https://www.etsy.com/shop/\{name}](https://www.etsy.com/shop/\{name}), [https://www.etsy.com/listing/\{id}/](https://www.etsy.com/listing/\{id}/)..., or https\://{shop}.etsy.com; never opened) or `name` (letters and digits, matched exactly, case-insensitively). Use it when the user pastes an Etsy link or names a shop. Short etsy.me links and bare IDs are refused: use get\_products or get\_shop for IDs. A shop or product Alura does not have comes back as a `fetch_unavailable` error; a name shared by several shops comes back as a conflict listing each candidate's ID.

* **Cost of `lookup_etsy_url`:** 1 API credit per call.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/lookup`](/api-reference/research/lookup).

| Argument | Type | Required | Description |
| - | - | - | - |
| `url` | string | No | An Etsy shop or listing URL, for example "[https://www.etsy.com/listing/4524717183/personalized-name-mug](https://www.etsy.com/listing/4524717183/personalized-name-mug)". Send `url` or `name`. |
| `name` | string | No | An Etsy shop name, for example "MugCo". Send `url` or `name`. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "url": "https://www.etsy.com/listing/4524717183/personalized-name-mug"
}
```

### `search_shops`

**Search Etsy shops.** Search Etsy shops (other sellers) in Alura's research data: filter by words, main category or sub-category name, country, Etsy sales count, estimated monthly sales, active listings, opening date and Star Seller status; sort by relevance, sales, estimated monthly sales, estimated revenue, reviews or newest. Returns up to 50 shop summaries per page; pass `next_cursor` back as `cursor` for the next page of the same search. Use it to find competitors or suppliers in a niche; get\_shop has a shop's full profile.

* **Cost of `search_shops`:** 10 API credits per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/shops`](/api-reference/research/shops/search).

| Argument | Type | Required | Description |
| - | - | - | - |
| `q` | string | No | Words that must all appear in the shop name, title or categories. |
| `category` | string | No | Main category name, for example "Home & Living". |
| `sub_category` | string | No | Sub-category name. |
| `country` | string | No | Two-letter country code, for example US. |
| `sales_min` | integer | No | Fewest sales (Etsy's count). |
| `sales_max` | integer | No | Most sales (Etsy's count). |
| `est_monthly_sales_min` | integer | No | Fewest estimated sales per month. |
| `active_listings_min` | integer | No | |
| `active_listings_max` | integer | No | |
| `opened_after` | string | No | Opened at or after this date, YYYY-MM-DD. |
| `star_seller` | boolean | No | |
| `sort` | `relevance`, `sales`, `est_monthly_sales`, `est_revenue`, `reviews`, `newest` | No | relevance (default) or a field; a field sort leaves out shops where that value is unknown. |
| `order` | `asc`, `desc` | No | desc (default) or asc; only with a field sort. |
| `cursor` | string | No | next\_cursor from the previous page of the same search. |
| `limit` | integer | No | Results per page, 1-50 (default 20). |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "q": "mug",
  "country": "US"
}
```

### `get_shop`

**Get an Etsy shop.** Get the full research profile of an Etsy shop (another seller) by its shop ID: name, country, category, active and digital listings, average price, favorites, reviews, Etsy's own lifetime sales count, Alura's estimated revenue and monthly sales (average, last month, 3-month trend), average listing score and when the data was last updated. `include` can add `top_products` (its 5 best-selling products) and `about` (its announcement, languages, custom-request flag and ships-from country, as stored by Alura; the announcement is the seller's own text). Use it after search\_shops or when the user names a shop.

* **Cost of `get_shop`:** 1 API credit per call.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/shops/{id}`](/api-reference/research/shops/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `id` | string | Yes | The Etsy shop ID as a string, for example "48911633". |
| `include` | string\[] | No | Extra data to add, free: top\_products, about. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "id": "48911633"
}
```

### `list_shop_products`

**List a shop's products.** List the active products of an Etsy shop (another seller) by its shop ID, 25 per call, as product summaries: price, category, reviews, Alura's estimated sales and revenue, listing score. Sort by estimated sales (default), lowest price or newest. Only shops Alura already has; another shop is not found. Pass `next_cursor` back as `cursor` for the next page of the same sort. Use it to see what a competitor sells best.

* **Cost of `list_shop_products`:** 1 API credit per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/shops/{id}/products`](/api-reference/research/shops/products).

| Argument | Type | Required | Description |
| - | - | - | - |
| `shop_id` | string | Yes | The Etsy shop ID as a string, for example "48911633". |
| `sort` | `sales`, `price`, `newest` | No | sales (default), price (lowest first) or newest; products where that value is unknown are left out. |
| `cursor` | string | No | next\_cursor from the previous page of the same shop and sort. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "shop_id": "48911633"
}
```

### `get_reviews`

**Get reviews.** Get the reviews of an Etsy shop or of one product (other sellers), newest first, 25 per call, with a summary: how many reviews match, their average rating, how many have each rating and how many carry a photo. Give `shop_id` for every review of the shop, or `product_id` for one product's. Filter by rating, words in the text, photo, language and date. The review text is the buyer's own words, returned as data. Only shops and products Alura already has: use get\_shop or get\_products first for a new one. Pass `next_cursor` back as `cursor` for the next page. Use it to learn what buyers praise or complain about.

* **Cost of `get_reviews`:** 1 API credit per page.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/research/shops/{id}/reviews`](/api-reference/research/shops/reviews), [`GET /v1/research/products/{id}/reviews`](/api-reference/research/products/reviews).

| Argument | Type | Required | Description |
| - | - | - | - |
| `shop_id` | string | No | An Etsy shop ID, for example "48911633": every review of the shop. Give this or product\_id. |
| `product_id` | string | No | An Etsy listing ID, for example "4524717183": the reviews of that product. Give this or shop\_id. |
| `rating` | integer | No | Only reviews with this many stars. |
| `q` | string | No | Words that must all appear in the review text. |
| `has_image` | boolean | No | true: only reviews with a photo; false: only reviews without one. |
| `language` | string | No | Only reviews in this language, as a code such as "en". |
| `from` | string | No | Written at or after this date, YYYY-MM-DD. |
| `to` | string | No | Written at or before this date, YYYY-MM-DD. |
| `cursor` | string | No | next\_cursor from the previous page of the same reviews and filters. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "shop_id": "48911633"
}
```

### `get_sales_history`

**Get sales history.** Get the monthly sales history of an Etsy shop or product (another seller's): for every completed calendar month, Alura's estimated sales, estimated revenue in USD (at the current price) and the reviews written that month, oldest first. Use it to see seasonality, growth or decline over time. Months with no data are null. Needs a plan that includes history.

* **Cost of `get_sales_history`:** 1 API credit per call.
* **Behavior:** Read-only: changes nothing. Returns public Etsy data.
* **Scope:** `research:read` (search and read Etsy market research).
* **Plan:** Growth or above. On other plans the call is refused with `plan_required` and costs nothing.
* **REST:** [`GET /v1/research/products/{id}/history`](/api-reference/research/products/history), [`GET /v1/research/shops/{id}/history`](/api-reference/research/shops/history).

| Argument | Type | Required | Description |
| - | - | - | - |
| `kind` | `shop`, `product` | Yes | Whose history: a shop (by shop ID) or a product (by listing ID). |
| `id` | string | Yes | The Etsy shop ID or listing ID as a string, for example "48911633". |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "kind": "product",
  "id": "4524717183"
}
```

### `browse_categories`

**Browse Etsy categories.** Browse Etsy's category tree. Pass `q` to find categories by name (each comes with its full path), pass `id` to get one category with its parent and direct subcategories, or pass nothing to list the top-level categories. Use `next_cursor` as `cursor` for the next page of a search. Use it to find a category ID for search\_products.

* **Cost of `browse_categories`:** Free (0 API credits).
* **Behavior:** Read-only: changes nothing. Works on Alura's own data only.
* **Scope:** `research:read` (search and read Etsy market research).
* **REST:** [`GET /v1/categories`](/api-reference/reference/categories/search), [`GET /v1/categories/{id}`](/api-reference/reference/categories/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `q` | string | No | Words in the category name, for example "mugs". |
| `id` | string | No | A category ID from an earlier result, to see its subcategories. |
| `cursor` | string | No | next\_cursor from the previous page of the same search. |
| `detail` | `concise`, `detailed` | No | `detailed` (default): every field this tool shows. `concise`: the key fields only, for long lists or a quick check. |

**Example arguments**

```json theme={null}
{
  "q": "mugs"
}
```


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