Etsy Product Query (_ehunt_productQuery)
Key Points
- Pagination:
pagestarts at 1;pageSizedefaults to 20, maximum 100 (recommended <= 50). - Range Parameters: Same approach as the store interface —
begin*/end*pairs. - Sorting:
sortByis 1~6 (upstreamsort_by).sortDesc: 1=descending, 2=ascending (different from_ehunt_storeQuerywhich uses 1/0). - Product Type
productType:1Handmade,2Vintage,3Digital,4Custom,9Other, use commas for multiple selection. - Currency:
currencyCodedefaults toUSD. - Category ID:
categoryis 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 for details.
Reference
Input/output parameter tables are in 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.
