StableSocial

# Social Media API > Pay-per-request social media data from 4 platforms. $0.06 per request (USDC on Base, Solana, or Tempo). ## How It Works: Async Two-Step Flow Every data request follows a two-step pattern: **pay to trigger**, then **poll with wallet auth**. ### Step 1: POST to trigger (paid) Send a POST request to any data endpoint with a payment header. Each call costs $0.06 in USDC on Base, Solana, or Tempo. On success you get back a **202 Accepted** with a signed JWT token: ```json { "token": "eyJhbGciOiJIUzI1NiIs..." } ``` The token is your receipt. It encodes everything needed to retrieve your data. No API keys, no sessions. ### Step 2: GET /api/jobs?token=... (free, SIWX wallet auth required) Poll this endpoint with your token. No payment required, but **SIWX wallet authentication is required** — the server verifies you are the same wallet that paid in Step 1. Only the paying wallet can poll for results. **Pending** — data is still being collected, poll again in a few seconds: ```json { "status": "pending", "message": "Poll again in a few seconds." } ``` **Finished** — your data is ready: ```json { "status": "finished", "data": { ... } } ``` **Failed** — collection failed (you are NOT charged when the trigger itself fails): ```json { "status": "failed", "error": "..." } ``` ### Complete Example ``` 1. POST /api/tiktok/profile {"handle": "someuser"} → 202 {"token": "eyJ..."} 2. GET /api/jobs?token=eyJ... (with SIWX wallet auth) → 200 {"status": "pending", "message": "Poll again in a few seconds."} 3. GET /api/jobs?token=eyJ... (a few seconds later, with SIWX wallet auth) → 200 {"status": "finished", "data": {"username": "someuser", ...}} ``` ### Token Details - Tokens expire after **30 minutes** (jobs typically finish in 5–60 seconds) - Tokens are replayable — you can poll as many times as needed - If a token expires, make a new paid POST request - Invalid or expired tokens return **401** - Polling with the wrong wallet (not the one that paid) returns **403** ## Data Freshness & Dependencies Data is fetched from social platforms on demand. To get complete results for dependent resources, update the base resource first: **Example — fetching followers:** 1. `POST /api/tiktok/profile` with `{"handle": "username"}` → get token, poll until finished 2. `POST /api/tiktok/followers` with `{"handle": "username"}` → get token, poll until finished **Example — fetching post replies:** 1. `POST /api/tiktok/profile` → trigger profile collection 2. `POST /api/tiktok/posts` → trigger post collection 3. `POST /api/tiktok/post-comments` with post ID → get comments ### Pagination After your first job finishes and returns data, use the `cursor` from `page_info` to fetch subsequent pages. Each page requires a new paid POST (which returns a new token to poll). Continue paginating while `page_info.has_next_page` is `true`. ## Endpoints All endpoints are POST requests that accept JSON bodies. All return 202 with a job token. All cost $0.06 per call. | Endpoint | Auth | Description | |---|---|---| | **GET /api/jobs?token=...** | **SIWX (free)** | Poll job status and retrieve results. Only the paying wallet can poll. | ### TikTok | Endpoint | Price | Description | Depends on | |---|---|---|---| | POST /api/tiktok/profile | $0.06 | Get user profile | — | | POST /api/tiktok/posts | $0.06 |Get user posts | profile | | POST /api/tiktok/post-comments | $0.06 |Get video comments | posts | | POST /api/tiktok/comment-replies | $0.06 |Get replies to a comment | post-comments | | POST /api/tiktok/followers | $0.06 |Get followers | profile | | POST /api/tiktok/following | $0.06 |Get following | profile | | POST /api/tiktok/search | $0.06 |Search posts by keyword | — | | POST /api/tiktok/search-hashtag | $0.06 |Search by hashtag | — | | POST /api/tiktok/search-profiles | $0.06 |Search user profiles | — | | POST /api/tiktok/search-music | $0.06 |Search posts by music/sound | — | ### Instagram | Endpoint | Price | Description | Depends on | |---|---|---|---| | POST /api/instagram/profile | $0.06 | Get user profile | — | | POST /api/instagram/posts | $0.06 |Get user posts | profile | | POST /api/instagram/post-comments | $0.06 |Get post comments | posts | | POST /api/instagram/comment-replies | $0.06 |Get replies to a comment | post-comments | | POST /api/instagram/followers | $0.06 |Get followers | profile | | POST /api/instagram/following | $0.06 |Get following | profile | | POST /api/instagram/stories | $0.06 |Get user stories | profile | | POST /api/instagram/highlights | $0.06 |Get user highlights | profile | | POST /api/instagram/search | $0.06 |Search posts by keyword | — | | POST /api/instagram/search-tags | $0.06 |Search by tag | — | ### Facebook | Endpoint | Price | Description | Depends on | |---|---|---|---| | POST /api/facebook/profile | $0.06 | Get page/user profile | — | | POST /api/facebook/posts | $0.06 |Get page/user posts | profile | | POST /api/facebook/post-comments | $0.06 |Get post comments | posts | | POST /api/facebook/comment-replies | $0.06 |Get replies to a comment | post-comments | | POST /api/facebook/followers | $0.06 |Get followers | profile | | POST /api/facebook/following | $0.06 |Get following | profile | | POST /api/facebook/search | $0.06 |Search posts by keyword | — | | POST /api/facebook/search-people | $0.06 |Search people profiles | — | | POST /api/facebook/search-pages | $0.06 |Search page profiles | — | | POST /api/facebook/search-groups | $0.06 |Search group profiles | — | ### Reddit | Endpoint | Price | Description | Depends on | |---|---|---|---| | POST /api/reddit/post | $0.06 | Get post details | — | | POST /api/reddit/post-comments | $0.06 |Get post comments | post | | POST /api/reddit/comment | $0.06 | Get comment details | — | | POST /api/reddit/search | $0.06 |Search posts by keyword | — | | POST /api/reddit/search-profiles | $0.06 |Search user profiles | — | | POST /api/reddit/subreddit | $0.06 |Get subreddit posts | — | ## Key Parameters - **handle** / **profile_id**: Username or ID of the target account - **max_page_size**: Results per page (default varies, max 100) - **max_followers**: How many followers to collect (default 500) - **max_posts** / **max_activities** / **max_results**: How many items to collect (default 50) - **cursor**: Pagination cursor from previous response - **order_by**: Sort order (date_desc, date_asc, id_desc) ## Error Handling - **400** — Bad request (missing/invalid parameters) - **401** — Invalid or expired job token (on /api/jobs) - **402** — Payment required (payment header missing or invalid) - **403** — Wrong wallet (polling with a wallet that didn't pay) - **502** — Upstream data collection failed If the POST trigger itself fails (bad params, entity not found), you get an immediate error and are NOT charged — payment only settles on 2xx responses. ## Authentication No API keys needed. Two mechanisms: - **Payment:** All POST trigger endpoints require payment (USDC on Base, Solana, or Tempo). Payment header is your authentication. - **SIWX (wallet auth):** The polling endpoint (`GET /api/jobs`) requires SIWX authentication to prove wallet ownership. Only the wallet that paid can poll for results. ## OpenAPI Spec Full schema available at `/openapi.json`