Introduction
SocialSpy API gives your product access to creator discovery, top-account leaderboards, viral topic generation, webhook events, and prepaid usage billing from the same host.
Quickstart
1. Create account
Signup stays on the SocialSpy portal. After account creation and OTP verification, come back here to manage the API workspace.
2. Create key
Open the API console, create an API key, and select the preset that matches the scopes and request rate you need.
curl --request GET \ --url 'https://api.socialspy.io/v2/top-accounts?country=US&limit=10' \ --header 'Authorization: Bearer sk_live_xxx'
Authentication
Bearer auth
Send the API key in the Authorization header for every request.
Authorization: Bearer sk_live_xxx
Base URL
Current products and webhooks live under the canonical v2 base.
https://api.socialspy.io/v2
Shared account
Login on the API site uses the same SocialSpy account as the portal, with email OTP verification before the dashboard opens.
Endpoint catalog
| Method | Path | Notes |
|---|---|---|
| GET | /v2/creators/search | Search creators by geography, niche, and audience filters. |
| GET | /v2/creators/explain | Explain why a creator matched the current search context. |
| GET | /v2/top-accounts | Read leaderboard payloads and explanation links. |
| GET | /v2/top-accounts/explain | Inspect ranking logic for a specific account. |
| POST | /v2/viral-topics/preview | Get synchronous preview ideas before committing to async generation. |
| POST | /v2/viral-topics/generations | Queue an async run and debit credits when the job is accepted. |
| GET | /v2/webhooks/endpoints | Inspect webhook endpoints associated with the current API key. |
Errors and billing
Response behavior
- 401 for missing or invalid API keys.
- 402 when the prepaid credit wallet is insufficient.
- 429 when the current key hits its rate limit.
- 503 when an upstream engine is temporarily unavailable.
Debit rules
- Successful sync responses debit credits on success.
- Accepted async jobs debit on acceptance.
- Invalid auth and validation failures do not debit credits.
- Temporary service failures do not permanently reduce balance.