Search Instagram posts by keyword — $0.06 per request, pay with USDC via MPP/x402
What it does
This endpoint searches Instagram posts by keyword through StableSocial's unified social media data API. It is one of 36 endpoints covering TikTok, Instagram, Facebook, and Reddit. You POST a JSON body with your search keywords and optional pagination/limit parameters, pay $0.06 per request in USDC (settled on Base, Solana, or Tempo L2), and receive a 202 response containing a JWT token. You then poll a separate free endpoint (GET /api/jobs?token=...) with SIWX wallet authentication to retrieve results once the async job completes (typically 5–60 seconds).
The search accepts a required `keywords` string and optional `max_posts` (default 50), `max_page_size` (default 50), and `cursor` for pagination. Each page of results requires a new paid POST. Results include `page_info` with `has_next_page` and a `cursor` for subsequent pages. No API keys or signup are required — payment via the MPP or x402 protocol header serves as authentication. Job tokens expire after 30 minutes and only the paying wallet can poll for results.
The endpoint uses an async two-step flow: Step 1 is the paid POST that triggers data collection and returns a JWT token; Step 2 is free polling via GET /api/jobs. If the trigger itself fails (bad params, entity not found), you are not charged. The API supports both x402 and MPP (method: tempo, intent: charge) payment protocols.
Capabilities
Use cases
- —Search Instagram for posts matching specific keywords for brand monitoring
- —Collect Instagram post data for sentiment analysis or market research
- —Build social listening dashboards that query Instagram content on demand
- —Agent-driven competitive analysis across Instagram content
Fit
Best for
- —AI agents needing on-demand Instagram post search without API key management
- —Pay-per-use social media research without monthly subscriptions
- —Programmatic keyword monitoring across Instagram posts
Not for
- —High-frequency real-time streaming of Instagram data (async polling adds latency)
- —Accessing private or non-public Instagram content
- —Use cases requiring free or bulk-discounted pricing at very high volumes
Quick start
# Step 1: Trigger search (requires MPP or x402 payment header)
curl -X POST https://stablesocial.dev/api/instagram/search \
-H 'Content-Type: application/json' \
-d '{"keywords": "artificial intelligence", "max_posts": 10}'
# Returns 202 with {"token": "eyJ..."}
# Step 2: Poll for results (free, requires SIWX wallet auth)
curl https://stablesocial.dev/api/jobs?token=eyJ...Example
Request
{
"keywords": "artificial intelligence",
"max_posts": 10,
"max_page_size": 10
}Response
{
"token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
}Endpoint
Quality
Full OpenAPI schema with clear request parameters, well-documented async flow, and confirmed pricing at $0.06/request. The probe returned 405 (not 402) because the endpoint only accepts POST, not HEAD/GET — this is expected behavior, not a failure. Response schema for the actual data payload is not documented (only the 202 token response is described). No example response data for finished jobs is available.
Warnings
- —Probe returned 405 because HEAD/GET were tried but this endpoint only accepts POST — endpoint is likely live but not confirmed via 402 challenge
- —No response schema documented for the finished job data payload (the actual Instagram search results)
- —Docs page at /docs returns 404; guidance is embedded in OpenAPI x-guidance field only
- —SIWX wallet authentication required for polling step — agents need wallet signing capability
Citations
- —Each request costs $0.06 in USDC on Base, Solana, or Tempohttps://stablesocial.dev
- —Async two-step flow: POST to trigger (paid, returns JWT token), then GET /api/jobs to poll (free, SIWX auth required)https://stablesocial.dev
- —Instagram search endpoint accepts keywords (required), max_posts, max_page_size, and cursor parametershttps://stablesocial.dev/openapi.json
- —Job 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
- —36 endpoints across TikTok, Instagram, Facebook, and Reddithttps://stablesocial.dev