Fetch TikTok user posts on-demand for $0.06 per request via pay-per-call social data API.
What it does
This endpoint (`POST /api/tiktok/posts`) retrieves a TikTok user's posts/videos given their username. It is part of StableSocial, a unified pay-per-request social media data API covering TikTok, Instagram, Facebook, and Reddit (36 endpoints total). Every call costs a flat $0.06 USD, settled via USDC on Base, Solana, or Tempo (pathUSD). No API keys or subscriptions are required — payment itself serves as authentication.
The workflow is asynchronous: a paid POST triggers data collection and returns a 202 response with a signed JWT token. You then poll `GET /api/jobs?token=...` (free, but requires SIWX wallet auth proving you're the paying wallet) until the job finishes, typically within 5–60 seconds. Tokens expire after 30 minutes. The posts endpoint depends on having first collected the user's profile via `/api/tiktok/profile`. Parameters include `handle` (required, TikTok username without @), `max_posts` (default 50, max 300), `order_by` (date_desc, date_asc, id_desc), `max_page_size` (default 50), and `cursor` for pagination. Each page requires a separate paid POST.
Payment is supported via both x402 and MPP (Tempo method, charge intent). The response schema for finished jobs is not documented in detail, but follows the pattern `{"status": "finished", "data": {...}}` with pagination info including `page_info.has_next_page` and a cursor for subsequent pages.
Capabilities
Use cases
- —Retrieve a TikTok creator's recent video posts for competitive analysis or trend monitoring
- —Build social listening dashboards that aggregate TikTok content by creator
- —Feed TikTok post data into AI agents for influencer research or content curation
- —Monitor brand-related TikTok accounts for new content programmatically
- —Collect TikTok post metadata (engagement, dates) for analytics pipelines
Fit
Best for
- —AI agents needing on-demand TikTok post data without managing API keys
- —Researchers collecting TikTok creator content at low per-request cost
- —Applications requiring unified social media data access across multiple platforms
Not for
- —High-frequency real-time streaming of TikTok content (async polling adds latency)
- —Bulk historical data dumps requiring millions of requests (cost adds up at $0.06 each)
- —Use cases requiring official TikTok API compliance or verified data provenance
Quick start
# Step 1: Trigger post collection (requires payment header)
curl -X POST https://stablesocial.dev/api/tiktok/posts \
-H 'Content-Type: application/json' \
-d '{"handle": "charlidamelio", "max_posts": 10}'
# → 202 {"token": "eyJ..."}
# Step 2: Poll for results (requires SIWX wallet auth)
curl 'https://stablesocial.dev/api/jobs?token=eyJ...' \
-H 'SIGN-IN-WITH-X: <siwx-token>'
# → 200 {"status": "finished", "data": {...}}Example
Request
{
"handle": "charlidamelio",
"order_by": "date_desc",
"max_posts": 10,
"max_page_size": 10
}Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Endpoint
Quality
Full OpenAPI schema with clear request parameters, detailed guidance docs embedded in the spec, and explicit pricing. The endpoint returned 405 on HEAD/GET probes, which is expected since it requires POST with payment. No response schema is documented for the actual data payload, and no example response body for finished jobs is provided, which limits completeness.
Warnings
- —Endpoint returned 405 on HEAD/GET probes — this is expected since it only accepts POST with a payment header, but live 402 challenge was not directly captured for this specific endpoint.
- —Response data schema for finished TikTok posts jobs is not documented — the structure of the returned post objects is unknown.
- —The /docs page returns 404; documentation is only available via the OpenAPI spec's x-guidance field and the landing page.
- —This endpoint depends on first calling /api/tiktok/profile for the same user — posts collection requires a prior profile collection.
Citations
- —Every endpoint costs $0.06 per request in USDC on Base, Solana, or Tempohttps://stablesocial.dev
- —The workflow is async: POST triggers collection returning a 202 with JWT token, then poll GET /api/jobshttps://stablesocial.dev
- —TikTok posts endpoint accepts handle, max_posts (max 300), order_by, max_page_size, and cursor parametershttps://stablesocial.dev/openapi.json
- —Tokens expire after 30 minutes; jobs typically finish in 5–60 secondshttps://stablesocial.dev
- —Posts endpoint depends on profile being collected firsthttps://stablesocial.dev
- —Payment supported via x402 and MPP (Tempo method, charge intent)https://stablesocial.dev/openapi.json
- —36 endpoints across TikTok, Instagram, Facebook, and Reddithttps://stablesocial.dev