> ## 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.

# Keywords and trends

> MCP tools for Etsy keyword volume and competition, related keywords, top results, search history and trending

These tools research Etsy search keywords and what's trending. They all need the **Search and read Etsy market research** permission (`research:read`) and only read.

## Try these prompts

Claude and GPT picked the tools shown for these prompts in Alura's evaluation runs.

| Ask your assistant | Tools it uses |
| - | - |
| How many people search for 'personalized gift' on Etsy each month, and how competitive is it? | `get_keyword_metrics` |
| Compare search volume and competition for the Etsy keywords 'gift for mom', 'crochet pattern' and 'coloring book'. | `get_keyword_metrics` |
| Suggest related Etsy keywords to 'gift for her' that I could target, with their search volumes. | `get_related_keywords` |
| Who are the top Etsy shops for the keyword 'crochet pattern'? | `get_keyword_top_results` |
| Is 'christmas gifts' a seasonal keyword on Etsy? Show me its monthly search history. | `get_keyword_history` |
| Which Etsy keywords are trending right now? | `get_trending` |

## Good to know

* **Keywords are text.** Pass the keyword itself, in any case and spacing; Alura matches it in the chosen language (English by default).
* **Search history** needs the Growth plan or above. On other plans the call is refused before anything is charged.
* **Average monthly sales** for a keyword is always empty for now. [Keyword market](/methodology/keyword-market) explains why.
* **Trending** covers products, shops and English keywords. See [Trending](/features/trending) for how items qualify.

## Tools

### `get_keyword_metrics`

**Get keyword metrics.** Get Etsy keyword research metrics for one or more keywords (up to 50) in one language: Alura's estimated monthly Etsy searches, Google searches, competition level and competing listings, 3-month and year-over-year search trend, average price and estimated monthly sales. Use it to compare keyword ideas or check a keyword before using it in a listing. Keywords Alura does not have come back in `unfetched` (with a code and `retry_after`), free.

* **Cost of `get_keyword_metrics`:** 1 API credit per item returned, or 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/keywords`](/api-reference/research/keywords/lookup), [`GET /v1/research/keywords/{id}`](/api-reference/research/keywords/get).

| Argument | Type | Required | Description |
| - | - | - | - |
| `keywords` | string\[] | Yes | Keyword text, for example \["personalized mug", "name mug"]; 1-50 keywords. |
| `language` | `ar`, `cs`, `da`, `de`, `en`, `es`, `fi`, `fr`, `hu`, `it`, `ja`, `ko`, `nl`, `no`, `pl`, `pt`, `ru`, `sv`, `zh-CN`, `zh-TW` | No | ISO code of the keyword language; default "en". |
| `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}
{
  "keywords": [
    "personalized mug"
  ]
}
```

### `get_related_keywords`

**Get related keywords.** Get Etsy keywords related to a keyword, in one language, with Alura's metrics for each: estimated monthly Etsy searches, Google searches, competition level and competing listings, 3-month and year-over-year trend, average price and estimated monthly sales. Most searched first, up to 25 per page; pass `next_cursor` back as `cursor` for more. Use it to find more keyword ideas around one. A keyword Alura does not have comes back in `unfetched` (with a code and `retry_after`), free.

* **Cost of `get_related_keywords`:** 1 API credit per page, 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/keywords/{id}/related`](/api-reference/research/keywords/related), [`GET /v1/research/keywords`](/api-reference/research/keywords/lookup).

| Argument | Type | Required | Description |
| - | - | - | - |
| `keyword` | string | Yes | The keyword text, for example "personalized mug". |
| `language` | `ar`, `cs`, `da`, `de`, `en`, `es`, `fi`, `fr`, `hu`, `it`, `ja`, `ko`, `nl`, `no`, `pl`, `pt`, `ru`, `sv`, `zh-CN`, `zh-TW` | No | ISO code of the keyword language; default "en". |
| `cursor` | string | No | next\_cursor from the previous page of the same call. |
| `limit` | integer | No | Keywords per page, 1-25 (default 25). |
| `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}
{
  "keyword": "personalized mug"
}
```

### `get_keyword_top_results`

**Get a keyword's top products or shops.** Get the best-selling Etsy products (other sellers' listings) or the top shops for a keyword (`kind`: products or shops), in one language: product summaries (price, category, reviews, estimated sales and revenue, listing score) or shop summaries (country, category, Etsy's sales count, estimated monthly sales and revenue, reviews, active listings). Products: every word of the keyword in the title, or the keyword as a tag, most estimated sales first. Shops: the shops behind the keyword's 500 best-selling products, ranked by those products' sales. Up to 50 per page; pass `next_cursor` back as `cursor` for more. Use it to see who wins a keyword before targeting it. A keyword Alura does not have comes back in `unfetched` (with a code and `retry_after`), free.

* **Cost of `get_keyword_top_results`:** 10 API credits per page, 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/keywords/{id}/products`](/api-reference/research/keywords/products), [`GET /v1/research/keywords/{id}/shops`](/api-reference/research/keywords/shops), [`GET /v1/research/keywords`](/api-reference/research/keywords/lookup).

| Argument | Type | Required | Description |
| - | - | - | - |
| `keyword` | string | Yes | The keyword text, for example "personalized mug". |
| `kind` | `products`, `shops` | Yes | products: the top products; shops: the top shops. |
| `language` | `ar`, `cs`, `da`, `de`, `en`, `es`, `fi`, `fr`, `hu`, `it`, `ja`, `ko`, `nl`, `no`, `pl`, `pt`, `ru`, `sv`, `zh-CN`, `zh-TW` | No | ISO code of the keyword language; default "en". |
| `cursor` | string | No | next\_cursor from the previous page of the same call. |
| `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}
{
  "keyword": "personalized mug",
  "kind": "products"
}
```

### `get_keyword_history`

**Get keyword search history.** Get a keyword's monthly search volume on Etsy (Alura's estimate) and Google, for every completed month Alura has, in one language. Use it to see seasonality and long-term demand before targeting a keyword. A month without a figure is null. Needs a plan that includes history. A keyword Alura does not have comes back in `unfetched` (with a code and `retry_after`), free.

* **Cost of `get_keyword_history`:** 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).
* **Plan:** Growth or above. On other plans the call is refused with `plan_required` and costs nothing.
* **REST:** [`GET /v1/research/keywords/{id}/history`](/api-reference/research/keywords/history), [`GET /v1/research/keywords`](/api-reference/research/keywords/lookup).

| Argument | Type | Required | Description |
| - | - | - | - |
| `keyword` | string | Yes | The keyword text, for example "personalized mug". |
| `language` | `ar`, `cs`, `da`, `de`, `en`, `es`, `fi`, `fr`, `hu`, `it`, `ja`, `ko`, `nl`, `no`, `pl`, `pt`, `ru`, `sv`, `zh-CN`, `zh-TW` | No | ISO code of the keyword language; default "en". |
| `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}
{
  "keyword": "personalized mug"
}
```

### `get_trending`

**Get trending on Etsy.** Get what is trending on Etsy (`kind`). products and shops: rising (default; estimated sales grew the most over the last 3 completed months against the 3 before, with at least 30 estimated sales a month) or new (listed or opened in the last 90 days, with at least 10 estimated sales a month, best sellers first), as product or shop summaries with `sales.est_trend_3m` and `sales.est_last_month`; `summary.trend_window` names the months compared. Only items Alura has refreshed recently can qualify, so coverage grows as Alura refreshes more of Etsy: an item missing from trending is not proof that it is not rising. keywords: the Etsy keywords whose search volume rose the most over the last 3 months against the 3 before, biggest rise first, with Alura's metrics for each (estimated monthly Etsy searches, Google searches, competition, 3-month and year-over-year trend, average price, estimated monthly sales). Up to 50 per page; pass `next_cursor` back as `cursor` for more. Use it when the user asks what is rising on Etsy or wants new product ideas.

* **Cost of `get_trending`:** 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/keywords/trending`](/api-reference/research/keywords/trending), [`GET /v1/research/products/trending`](/api-reference/research/products/trending), [`GET /v1/research/shops/trending`](/api-reference/research/shops/trending).

| Argument | Type | Required | Description |
| - | - | - | - |
| `kind` | `keywords`, `products`, `shops` | Yes | What is trending: keywords, products or shops. |
| `type` | `rising`, `new` | No | For products and shops: rising (default) or new. |
| `language` | `en` | No | For keywords: ISO code of the keyword language ("en" for now); default "en". |
| `category_id` | string | No | For products: an Etsy category ID from browse\_categories; includes every category under it. |
| `category` | string | No | For shops: the main category by name, for example "Home & Living". |
| `price_min` | number | No | For products: lowest price in USD. |
| `price_max` | number | No | For products: highest price in USD. |
| `est_sales_min` | integer | No | For products: fewest estimated lifetime sales. |
| `est_sales_max` | integer | No | For products: most estimated lifetime sales. |
| `sales_min` | integer | No | For shops: fewest sales (Etsy's count). |
| `sales_max` | integer | No | For shops: most sales (Etsy's count). |
| `est_monthly_sales_min` | integer | No | For products and shops: fewest estimated sales per month. |
| `est_monthly_sales_max` | integer | No | For products and shops: most estimated sales per month. |
| `cursor` | string | No | next\_cursor from the previous page of the same call. |
| `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}
{
  "kind": "products",
  "type": "rising"
}
```


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