SoldScope API FAQ
Olivia Reyes
Quick answers to the most common SoldScope API questions, from token setup to handling rate limits and asynchronous searches.
Authentication & access
Where do I get an API token?
In your SoldScope account, go to API Access, click Create token, give it a name, and copy the token. It's shown only once - store it securely.
I lost my token. Can I see it again?
No. Tokens are shown once at creation for security reasons. If you've lost a token, create a new one in API Access and update your integration. You can revoke the old token at any time.
How do I revoke a token?
Open API Access in your account and delete the token from the list. Any request using that token will start returning 401 Unauthorized immediately.
Can I have multiple tokens?
Yes. We recommend creating a separate token for each integration or environment (e.g. one for staging, one for production). That way you can revoke a single token without affecting your other integrations.
How do I check that my token is working?
Send a GET /auth/check request with your token in the Authorization header. A 200 response with your account info means everything is configured correctly.
Rate limits & billing
Which endpoints count toward my quota?
Endpoints marked with the ◈ symbol in the API reference sidebar (and the Metered badge on the endpoint page). These are typically the ones that run new searches or generate fresh research data. Authentication, account info, and fetching previously saved data don't count toward your quota.
How can I check how many requests I have left?
Every API response includes rate limit headers:
X-API-RateLimit-Limit- your total monthly quotaX-API-RateLimit-Remaining- requests left until resetX-API-RateLimit-Reset- date of the next reset
What happens when I hit my limit?
Metered endpoints will return 402 Payment Required until your quota resets or you upgrade your plan. Free endpoints keep working normally. Quotas reset on the first day of each billing cycle.
Should my code retry a 402 response?
No. 402 Payment Required means the request is valid but your quota is exhausted - retrying won't succeed until the next billing cycle or an upgrade. Treat it as a permanent error for the current period and surface it to the user instead of putting it in your retry loop.
Do failed requests count toward my quota?
Failed requests (4xx, 5xx responses) do not count toward your quota. Only successful metered calls consume from your monthly limit.
Does paginating through results consume extra quota?
No. The first request runs the search and counts toward your quota; subsequent pages of the same search (using searchId) are free. The same applies to fetching variations or replaying past searches.
How do I increase my limit?
Upgrade to a higher plan on the pricing page. The new quota applies immediately.
Searches & workflows
My multi-ASIN search returned status: 0. Is something wrong?
No - status: 0 means «started». Multi-ASIN and keyword searches run asynchronously, so the initial response confirms the search has been queued. Poll GET /keyword-research/searches/{id}/progress until searchStatus: 2 (completed) or searchStatus: 13 (failed), then fetch the results.
How often should I poll for search progress?
Every 2–5 seconds is reasonable. Stop polling once you receive searchStatus: 2 or searchStatus: 13 - both are terminal states.
What does searchStatus: 13 mean?
The search failed because the keyword or ASIN produced no results. Treat this as a normal outcome (not an error in your integration) and surface it appropriately to the user.
Can I search more than 10 ASINs at once?
No. Multi-ASIN searches accept 2 to 10 ASINs per call. For larger batches, run multiple searches in parallel.
What's the difference between id and nodeId for categories?
id is SoldScope's internal database identifier - used only in the path of GET /product-research/categories/{id}/children. nodeId is Amazon's category node identifier - this is what goes into the filters[categories][] parameter when running a product search.
Variations endpoint returned 404. What happened?
Variations are served from a one-hour in-memory cache populated by the original search. If the cache has expired, re-run the search by calling GET /product-research/products?searchId={id} to refresh it, then fetch variations again.
Can I replay a past search without spending against my quota?
Yes. Use GET /product-research/searches to list past searches, then pass the returned id as searchId in a new request to replay it without consuming quota.
Tools & integration
Which programming languages are supported?
Any language that can make HTTPS requests. The API reference includes ready-to-copy code samples in curl, JavaScript, Python, PHP, and other popular languages.
Is there an official SDK?
Not at the moment. The API uses standard REST conventions and JSON, so any HTTP client works. We may publish official SDKs in the future based on demand.
Can I test endpoints without writing code?
Yes. The API reference includes an interactive client - paste your token once and you can run any endpoint directly from the documentation page.
Are there sandbox or staging credentials?
No separate sandbox is available. Free endpoints (like GET /auth/check or listing past searches) are safe to call freely while you're integrating, and won't affect your quota.
General
The API is missing an endpoint I need. What now?
Reach out to support - we're actively developing the API and prioritize new endpoints based on user requests.
How do I know when new endpoints are added?
The API reference is auto-generated from the live API, so new endpoints appear there as soon as they ship. We recommend bookmarking the reference and checking it periodically.
Where can I report a bug or get help?
Contact support with as much detail as possible: the endpoint, the request payload, the full response (including headers), and the time of the request. That helps us diagnose much faster.