Skip to content

nexscope-ai/nexscope-ecommerce-skills / ecommerce-etsy-product-query

ecommerce.etsy-product-query

Verified

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.

FileKindSize
SKILL.mdskill md2.9 KB
manifest.jsonconfig323 B
references/api.mdmarkdown7.3 KB
scripts/etsy_product_query.pyscript6.5 KB
---
name: ecommerce.etsy-product-query
description: 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.
---

# Etsy Product Query (`_ehunt_productQuery`)

## Key Points

- **Pagination**: `page` starts at 1; `pageSize` defaults to 20, maximum 100 (recommended <= 50).
- **Range Parameters**: Same approach as the store interface — `begin*` / `end*` pairs.
- **Sorting**: `sortBy` is **1~6** (upstream `sort_by`). `sortDesc`: **1=descending, 2=ascending** (different from `_ehunt_storeQuery` which uses 1/0).
- **Product Type** `productType`: `1` Handmade, `2` Vintage, `3` Digital, `4` Custom, `9` Other, use commas for multiple selection.
- **Currency**: `currencyCode` defaults to `USD`.
- **Category ID**: `category` is a single category ID; use the category search skill to find the ID first.

## Script (Optional)

Command-line debugging: `python scripts/etsy_product_query.py ''<JSON>''` (requires `NEXSCOPE_API_KEY`). See [references/api.md](references/api.md) for details.

## Reference

Input/output parameter tables are in [references/api.md](references/api.md).

## Authentication

Set the `NEXSCOPE_API_KEY` environment variable. If authentication fails (401/402) or you see insufficient balance errors, visit https://www.nexscope.ai/help/skills-external-access?co-from=skillNS to get an API Key or top up credits.

## Credit Consumption

Dynamic pricing: credits consumed = number of products returned x 1.8. Billed per page of results returned; fetching the next page is essentially a new request, billed again based on the new page''s result count.

> **Important**: This skill''s cost scales dynamically and may consume a significant number of credits in a single call. You must warn the user and let them decide whether to continue.

## API Key request rate

All Nexscope API Keys belonging to the same user share one request-rate allowance for public API execution. The allowance is measured over any rolling 1-second window. Your RPS depends on your account entitlements; do not assume every user has a fixed 1 RPS. A single Skill operation may make multiple public API requests, and each request uses this allowance.

If an execution request returns HTTP 429 with outer code `13012`, the request-rate allowance was exceeded. Honor the returned `Retry-After` before considering another request. Outer code `13013` means the concurrent-request limit was exceeded, not the rate limit; honor its `Retry-After` when supplied. Inspect the response and reconcile state before retrying. Never automatically replay a write operation or a request whose outcome is unclear.
receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementationStars: 322kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 322kUpdated Claude CodeCodexVerifiedInstall
using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallbackStars: 322kUpdated Claude CodeCodexVerifiedInstall
verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysStars: 322kUpdated Claude CodeCodexVerifiedInstall