Skip to main content

​
API

The API provides a consistent request flow for social data collection: 
submit -> task_id -> task status/results/files

​
Authentication

Authorization: Bearer YOUR_API_KEY
Content-Type: application/json

​
Submit Endpoints

Each product API has its own resource path:
PlatformAPIEndpoint
InstagramPostsPOST /v1/instagram/posts
InstagramReelsPOST /v1/instagram/reels
InstagramSearchPOST /v1/instagram/search
InstagramFollowers CountPOST /v1/instagram/followers-count
FacebookPagesPOST /v1/facebook/pages
FacebookPostsPOST /v1/facebook/posts

​
Common Submit Body

Input fields are sent directly in the JSON body. 
{
  "urls": ["https://www.instagram.com/p/POST_CODE/"],
  "results_limit": 10,
  "callback_url": "https://your-domain.com/webhook"
}
callback_url is optional. If provided, SocQ sends a POST request after the task reaches a terminal state. See Callbacks for the payload shape.

​
Result Storage

SocQ stores two forms of results:
StoragePurpose
Normalized recordsReturned by /v1/tasks/{task_id} after the task succeeds
Raw JSONL fileDownload from /v1/tasks/{task_id}/files
Raw files use this path format: 
agent-results/{task_id}/raw_jsonl.jsonl.gz

​
Billing

Agent APIs are billed by returned result record. The submit request may reserve credits from results_limit or the number of submitted URLs/usernames; after the task finishes, SocQ settles the final charge from the actual result_count and returns any unused reserved credits.