Etsy
Query Etsy products with multi-dimensional filters (keyword/URL, price, sales, favorites, reviews, listing date, category, handmade/vintage types, Pick/Bestseller/Raving tags).
nexscope_etsy_product_queryhttps://api.nexscope.ai/api/skill-api/v2/mcptools/callUse OAuth 2.1 Authorization Code with PKCE and the mcp:tools scope for standard remote clients. API keys remain supported as a compatibility option while v1 integrations migrate.
Authorization: Bearer nk-xxxxxxxxxxxxxxxxxIf authentication is missing or invalid, ask the user to open API Access and copy a valid key before calling this tool.
Initialize an MCP 2025-11-25 Streamable HTTP session at https://api.nexscope.ai/api/skill-api/v2/mcp, then use tools/call with the MCP tool name below. The arguments object should match the table on this page.
{
"jsonrpc": "2.0",
"id": "etsy-product-query-1",
"method": "tools/call",
"params": {
"name": "nexscope_etsy_product_query",
"arguments": {
"pageSize": 20,
"searchKey": "phone case",
"page": 1
}
}
}MCP 2025-11-25 · Streamable HTTPhttps://www.nexscope.ai/mcp-map/etsy-product-queryProgress is delivered on the original POST SSE response when the client supplies a progress token and the tool has real execution stages. GET SSE carries server notifications such as tool-list changes. Creating an asynchronous task or calling an external provider may consume credits; reconnecting must query the existing task instead of submitting it again.
| Name | Type | Required | Description |
|---|---|---|---|
beginFavorites | integer | optional | Favorite count (start), combined with end value to form the upstream favorites range Example: 1 |
beginFavoritesWeekly | integer | optional | Weekly new favorites (start), combined with end value to form the upstream favorites_weekly range Example: 1 |
beginPrice | number | optional | Price (start), combined with end price to form the upstream price range (e.g., 20~100). When only one side is provided, the upstream returns start~ or ~end Example: 1 |
beginReviews | integer | optional | Review count (start), combined with end value to form the upstream reviews range Example: 1 |
beginReviewsWeekly | integer | optional | Weekly new reviews (start), combined with end value to form the upstream reviews_weekly range Example: 1 |
beginSales | integer | optional | Total sales (start), combined with end value to form the upstream sales range Example: 1 |
beginSalesWeekly | integer | optional | Weekly sales (start), combined with end value to form the upstream sales_weekly range (e.g., 1~100) Example: 1 |
category | string | optional | Product category ID (single category), see the Category Query API Example: {} |
country | string | optional | Shipping country Example: {} |
currencyCode | string | optional | Currency code, default USD Example: USD |
endFavorites | integer | optional | Favorite count (end) Example: 1 |
endFavoritesWeekly | integer | optional | Weekly new favorites (end) Example: 1 |
endPrice | number | optional | Price (end), combined with start price to form the upstream price range Example: 1 |
endReviews | integer | optional | Review count (end) Example: 1 |
endReviewsWeekly | integer | optional | Weekly new reviews (end) Example: 1 |
endSales | integer | optional | Total sales (end) Example: 1 |
endSalesWeekly | integer | optional | Weekly sales (end) Example: 1 |
isBestsell | integer | optional | Whether the product is a bestseller Example: 1 |
isPick | integer | optional | Whether the product is a Pick item Example: 1 |
isRaving | integer | optional | Whether the product is a Raving item Example: 1 |
listedTime | string | optional | Listing time no earlier than this date (YYYY-MM-DD) Example: {} |
page | integer | optional | Page number (starting from 1) Example: 1 |
pageSize | integer | optional | Items per page, default 20, max 100, recommended not to exceed 50 Example: 20 |
productType | string | optional | Product type, comma-separated for multiple: 1=Handmade 2=Vintage 3=Digital 4=Custom 9=Other Example: {} |
searchKey | string | optional | Search keyword or Etsy product URL Example: {} |
sortBy | integer | optional | Sort field (corresponds to upstream sort_by, values 1~6) Example: 1 |
sortDesc | integer | optional | Sort direction (corresponds to upstream desc). Schema example: descending 1, ascending 2 (encoding differs from store query's sortDesc) Example: 1 |
status | integer | optional | Product status (example: 1=active, 0=inactive) Example: 1 |
Treat structuredContent as the programmatic API response payload.
| Name | Type | Required | Description |
|---|---|---|---|
data | any | required | Data value used by this API operation. |
code | integer | required | 0 means accepted or successful; nonzero is a platform error. |
msg | string | null | required | Msg value used by this API operation. |
ts | string | required | Epoch milliseconds. |
time | string | required | Server local time: yyyy-MM-dd HH:mm:ss. |
cost | string | required | Elapsed milliseconds, never credits; -1 outside web requests. |
traceId | string | null | required | Trace id value used by this API operation. |
| Name | Type | Required | Description |
|---|---|---|---|
data | object | required | Data value used by this API operation. |
data.total | integer | optional | Record count (number of records returned on this page, for alignment with list length) Example: 1 |
data.sourceTool | string | optional | Tool type: ehunt Example: null |
data.sourceType | string | optional | Source type: etsy Example: null |
data.columns | array |
{
"pageSize": 20,
"searchKey": "phone case",
"page": 1
}{
"data": {
"total": 1,
"columns": [],
"costToken": 1,
"productNum": 1,
"products": [
{
"favorites": 1,
"favoritesWeekly": 1,
"imageUrl": "https://example.com/image.jpg",
"isBestsell": 1,
"isPick": 1,
"isRaving": 1,
"price": 1,
"productUrl": "https://example.com/image.jpg",
"reviews": 1,
"reviewsWeekly": 1,
"salesTotal": 1,
"salesWeekly": 1,
"status": 1
}
]
},
"code": 0,
"msg": null,
"ts": "0",
"time": "2026-01-01 00:00:00",
"cost": "-1",
"traceId": null
}Rendered columns Example: [] |
data.costToken | integer | optional | Token consumption (estimated based on records returned on this page) Example: 1 |
data.productNum | integer | optional | Total number of matching products (upstream product_num) Example: 1 |
data.title | string | optional | Title Example: null |
data.type | string | optional | Render style Example: null |
data.products | array | optional | Etsy product list Example: [] |
data.products[] | object | required | Item in data products. |
data.products[].category | string | optional | Category name Example: null |
data.products[].favorites | integer | optional | Favorite count Example: 1 |
data.products[].favoritesWeekly | integer | optional | Weekly new favorites Example: 1 |
data.products[].imageUrl | string | optional | Main image URL Example: https://example.com/image.jpg |
data.products[].isBestsell | integer | optional | Whether bestseller: 1=Yes Example: 1 |
data.products[].isPick | integer | optional | Whether Pick: 1=Yes Example: 1 |
data.products[].isRaving | integer | optional | Whether Raving: 1=Yes Example: 1 |
data.products[].price | number | optional | Price Example: 1 |
data.products[].productUrl | string | optional | Product link Example: https://example.com/image.jpg |
data.products[].releaseTime | string | optional | Listing/release time Example: null |
data.products[].reviews | integer | optional | Review count Example: 1 |
data.products[].reviewsWeekly | integer | optional | Weekly new reviews Example: 1 |
data.products[].salesTotal | integer | optional | Total sales Example: 1 |
data.products[].salesWeekly | integer | optional | Weekly sales Example: 1 |
data.products[].shipsFrom | string | optional | Shipping country Example: null |
data.products[].status | integer | optional | Product status: 1=active, 0=inactive Example: 1 |
data.products[].storeName | string | optional | Store name Example: null |
data.products[].tags | string | optional | Tags Example: null |
data.products[].title | string | optional | Product title Example: null |
data.costTime | integer | optional | Execution time reported by the upstream provider. Example: null |
data.page | integer | optional | Current page returned by the upstream provider. Example: null |
data.pageSize | integer | optional | Page size returned by the upstream provider. Example: null |
data.pageItemCount | integer | optional | Item count on the current page returned by the upstream provider. Example: null |
data.totalPage | integer | optional | Total page count returned by the upstream provider. Example: null |
data.dataSnapshotMonth | string | optional | Data snapshot month returned by the upstream provider. Example: null |
| Name | Type | Required | Description |
|---|---|---|---|
data | null | required | Data value used by this API operation. |