Etsy Marketplace

Etsy Product Query

Query Etsy products with multi-dimensional filters (keyword/URL, price, sales, favorites, reviews, listing date, category, handmade/vintage types, Pick/Bestseller/Raving tags). Trigger when user mentions Etsy products, Etsy listings, Etsy product sourcing, Etsy bestsellers, Etsy handmade, Etsy vintage, Etsy items, or Etsy product query — even if the tool name is not mentioned, as long as the need is to search products, view sales/price/tags, or filter items on Etsy.

post/api/skill-api/v1/skills/etsy-product-query/run

Request

  • Base URL: https://api.nexscope.ai
  • URL: https://api.nexscope.ai/api/skill-api/v1/skills/etsy-product-query/run
  • Auth: HTTP bearer

Headers

X-Nexscope-Http-Status'legacy' | 'semantic'

Use semantic for HTTP error statuses on run and task-result requests. Without this header v1 retains legacy status behavior. The JSON envelope is unchanged; code 0 means success or acceptance, not asynchronous completion.

Request body

beginFavoritesinteger

Favorite count (start), combined with end value to form the upstream favorites range

beginFavoritesWeeklyinteger

Weekly new favorites (start), combined with end value to form the upstream favorites_weekly range

beginPricenumber

Price (start), combined with end price to form the upstream price range (e.g., 20100). When only one side is provided, the upstream returns start or ~end

beginReviewsinteger

Review count (start), combined with end value to form the upstream reviews range

beginReviewsWeeklyinteger

Weekly new reviews (start), combined with end value to form the upstream reviews_weekly range

beginSalesinteger

Total sales (start), combined with end value to form the upstream sales range

beginSalesWeeklyinteger

Weekly sales (start), combined with end value to form the upstream sales_weekly range (e.g., 1~100)

categorystring

Product category ID (single category), see the Category Query API

countrystring

Shipping country

currencyCodestring

Currency code

endFavoritesinteger

Favorite count (end)

endFavoritesWeeklyinteger

Weekly new favorites (end)

endPricenumber

Price (end), combined with start price to form the upstream price range

endReviewsinteger

Review count (end)

endReviewsWeeklyinteger

Weekly new reviews (end)

endSalesinteger

Total sales (end)

endSalesWeeklyinteger

Weekly sales (end)

isBestsellinteger

Whether the product is a bestseller

isPickinteger

Whether the product is a Pick item

isRavinginteger

Whether the product is a Raving item

listedTimestring

Listing time no earlier than this date (YYYY-MM-DD)

pageinteger

Page number (starting from 1)

pageSizeinteger

Items per page, max 100, recommended not to exceed 50

productTypestring

Product type, comma-separated for multiple: 1=Handmade 2=Vintage 3=Digital 4=Custom 9=Other

searchKeystring

Search keyword or Etsy product URL

sortByinteger

Sort field (corresponds to upstream sort_by, values 1~6)

sortDescinteger

Sort direction (corresponds to upstream desc). Schema example: descending 1, ascending 2 (encoding differs from store query's sortDesc)

statusinteger

Product status (example: 1=active, 0=inactive)

Example request

{
  "page": 1,
  "pageSize": 10,
  "searchKey": "phone case"
}

Response

Successful response.

codeinteger required

0 means accepted or successful; nonzero is a platform error.

msgstring nullable required
tsstring required

Epoch milliseconds.

timestring required

Server local time: yyyy-MM-dd HH:mm:ss.

coststring required

Elapsed milliseconds, never credits; -1 outside web requests.

traceIdstring nullable required

Example response

{
  "data": {
    "total": 1,
    "costToken": 1,
    "productNum": 1,
    "products": []
  }
}

Changes

No recorded changes to this operation across all 1 revision of this API.