Etsy Product Query API
REST API and MCP service documentation generated from server-side API definitions. Responses use the shared code, msg, and data envelope.
API selector
REST API and MCP service documentation generated from server-side API definitions. Responses use the shared code, msg, and data envelope.
Filter Etsy products by keyword, URL, price, sales, favorites, reviews, listing date, category, product type, and marketplace badges.
https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/runnexscope_etsy_product_queryAll run endpoints require a user API key. Send it as a bearer token in the Authorization header.
Authorization: Bearer nk-xxxxxxxxxxxxxxxxxhttps://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/runRequest parameters documented by ecommerce.etsy-product-query.
| Slug | etsy-product-query |
| Headers | Authorization: Bearer nk-...Content-Type: application/json |
| Request body | API-specific JSON object. |
| Response body | Platform envelope: code, msg, data, ts, time, cost, traceId. Inspect data.status for asynchronous completion. |
| Code | Description |
|---|---|
| 200 | HTTP request completed. Check JSON code; only 0 indicates business success or acceptance. |
| 400 | Request JSON or required API parameters are invalid. |
| 401 | API key is missing, invalid, or cannot be matched to a user. |
| 5xx | API execution or upstream service failed. |
Replace YOUR_API_KEY, then run this command in your terminal.
curl -X POST 'https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run' \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"pageSize": 20,
"page": 1,
"searchKey": "phone case"
}'https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/runSend a JSON request to execute this API and receive the documented response payload.
| Method | POST |
| Path | https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run |
| Auth | Bearer API key |
| Content-Type | application/json |
| 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 |
{
"pageSize": 20,
"page": 1,
"searchKey": "phone case"
}Platform response envelope. code 0 indicates success or acceptance; data contains the business result.
{
"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
}| 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 |
| Code | Description |
|---|---|
| 200 | HTTP request completed. Check JSON code; only 0 indicates business success or acceptance. |
| 400 | Request JSON or required API parameters are invalid. |
| 401 | API key is missing, invalid, or cannot be matched to a user. |
| 5xx | API execution or upstream service failed. |
Source, freshness, coverage, rate limits, and estimation notes are not specified in this API definition unless they appear in the request or response field documentation above. Do not assume official marketplace data or real-time freshness when it is not explicitly documented.
Connect remote agents through the standard MCP 2025-11-25 Streamable HTTP endpoint. Use OAuth 2.1 Authorization Code with PKCE, or an API key for compatibility.
POST https://api.nexscope.ai/api/skill-api/v2/mcp
MCP-Protocol-Version: 2025-11-25
Content-Type: application/jsonOAuth clients request the mcp:tools scope. The endpoint's 401 response advertises protected-resource metadata for authorization discovery.
{
"jsonrpc": "2.0",
"id": "tool-call-1",
"method": "tools/call",
"params": {
"name": "nexscope_etsy_product_query",
"arguments": {
"pageSize": 20,
"page": 1,
"searchKey": "phone case"
}
}
}Existing API-key clients can continue using the compatibility endpoint. New integrations should use MCP v2.
GET / POST /api/skill-api/v1/mcpExecute the current API with your API key and JSON payload.
Send a real request with the same contract shown in the reference.
https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/runnexscope_etsy_product_querycurl -X POST \
https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run \
-H "Authorization: Bearer nk-..." \
-H "Content-Type: application/json" \
-d '{ "pageSize": 20, "page": 1, "searchKey": "phone case" }'No response yet. Run the request to see the response here.
Retrieve public Etsy listing details from a validated marketplace URL for product, pricing, shop, and competitive research workflows.
Find Etsy category IDs by category name, ID, or parent ID for product and store filtering. Review request and response fields.
Search Etsy stores by keyword, category, country, status, ratings, sales, favorites, reviews, and opening date with pagination and sorting.
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 |
country | string | optional | Shipping country |
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) |
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 |
searchKey | string | optional | Search keyword or Etsy product URL |
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 |
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 | optional | 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. |