Fetch Instagram user stories on demand for $0.06 per request via pay-per-call social data API.
What it does
This endpoint retrieves Instagram stories for a given user. It is part of StableSocial, a unified pay-per-request social media data API covering TikTok, Instagram, Facebook, and Reddit across 36 endpoints. Every call costs a flat $0.06 in USDC (settled on Base, Solana, or Tempo). No API keys or subscriptions are required — payment itself serves as authentication.
The endpoint uses an async two-step flow. You POST to `/api/instagram/stories` with a JSON body containing the target Instagram username (the `handle` field is required). On success, you receive a 202 response with a signed JWT token. You then poll `GET /api/jobs?token=...` (free, but requires SIWX wallet auth proving you are the paying wallet) until the job status is "finished" and your story data is returned. Jobs typically complete in 5–60 seconds; tokens expire after 30 minutes. If the trigger POST itself fails (e.g., bad parameters), you are not charged.
This endpoint depends on the user's profile having been collected first via `POST /api/instagram/profile`. Pagination is supported via `cursor` and `max_page_size` parameters. The API supports both x402 and MPP (Tempo method, charge intent) payment protocols.
Capabilities
Use cases
- —Monitoring competitor Instagram story activity for brand intelligence
- —Collecting Instagram story data for social media analytics dashboards
- —Enabling AI agents to research influencer story content programmatically
- —Archiving or auditing Instagram stories for compliance or reporting
- —Aggregating story metadata across multiple Instagram accounts
Fit
Best for
- —AI agents needing on-demand Instagram story data without managing credentials
- —Developers who want pay-per-call pricing instead of monthly subscriptions
- —Applications that need cross-platform social data from a single unified API
Not for
- —High-frequency bulk scraping requiring thousands of requests per second at lower cost
- —Use cases requiring real-time streaming of stories as they are posted
- —Accessing private or non-public Instagram accounts
Quick start
# Step 1: Trigger story collection (requires payment header)
curl -X POST https://stablesocial.dev/api/instagram/stories \
-H 'Content-Type: application/json' \
-d '{"handle": "natgeo"}'
# → 202 {"token": "eyJ..."}
# Step 2: Poll for results (free, SIWX wallet auth required)
curl https://stablesocial.dev/api/jobs?token=eyJ...Example
Request
{
"handle": "natgeo",
"max_page_size": 50
}Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Endpoint
Quality
Full OpenAPI schema with clear request parameters, detailed guidance docs, and confirmed pricing ($0.06/request). The endpoint returned 405 on HEAD/GET probes, which is expected since it only accepts POST. No example response body for the actual story data is documented, and the /docs page returns 404, so response shape must be inferred.
Warnings
- —Probe returned 405 on HEAD/GET because this endpoint only accepts POST — this does not indicate the endpoint is down.
- —No documented response schema for the actual story data payload (only the job token response is described).
- —The /docs page returns 404; all documentation comes from the OpenAPI spec x-guidance field and the landing page.
- —This endpoint depends on first calling POST /api/instagram/profile for the target user.
Citations
- —Every endpoint costs $0.06 per request in USDC on Base, Solana, or Tempohttps://stablesocial.dev
- —The endpoint uses an async two-step flow: POST to trigger (paid), then poll GET /api/jobs (free with SIWX auth)https://stablesocial.dev
- —Instagram stories endpoint requires the handle parameter and depends on profile being collected firsthttps://stablesocial.dev
- —Tokens expire after 30 minutes; jobs typically finish in 5–60 secondshttps://stablesocial.dev
- —Payment only settles on 2xx responses; failed triggers are not chargedhttps://stablesocial.dev
- —Supports both x402 and MPP (Tempo method, charge intent) payment protocolshttps://stablesocial.dev