Products and shops

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 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.
Mature listings are left out over MCP. See 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.

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

{
  "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}, GET /v1/research/products.

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

{
  "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.

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

{
  "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.

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

{
  "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/listing/{id}/…, or https://.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.

Argument	Type	Required	Description
`url`	string	No	An Etsy shop or listing URL, for example “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

{
  "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.

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

{
  "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}.

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

{
  "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.

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

{
  "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, GET /v1/research/products/{id}/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

{
  "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, GET /v1/research/shops/{id}/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

{
  "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, GET /v1/categories/{id}.

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

{
  "q": "mugs"
}

​Try these prompts

​Good to know

​Tools

​search_products

​get_products

​find_similar_products

​get_product_tags

​lookup_etsy_url

​search_shops

​get_shop

​list_shop_products

​get_reviews

​get_sales_history

​browse_categories

Try these prompts

Good to know

Tools

`search_products`

`get_products`

`find_similar_products`

`get_product_tags`

`lookup_etsy_url`

`search_shops`

`get_shop`

`list_shop_products`

`get_reviews`

`get_sales_history`

`browse_categories`