SocialiQDocs
PlaygroundOpenAPIGet API key

Resources

Posts

A post is the core content object — a TikTok video, Instagram reel, YouTube video, tweet, Reddit thread, or LinkedIn article. Everything below hangs off a post.

Get a post

GET/v1/{platform}/posts/{id}

Fetch one normalized post by its platform ID.

FieldInTypeDescription
platformrequiredpathenumPlatform slug, e.g. tiktok.
idrequiredpathstringThe platform post ID.
include_rawdefault falsequerybooleanAppend the raw platform payload alongside normalized data.

Request

curl "https://api.socialiq.dev/v1/tiktok/posts/7350810998023949599" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_b2c3d4e5f6a7b8c9d0e1",  "data": {    "id": "7350810998023949599",    "type": "post",    "platform": "tiktok",    "text": "Normalized social media object ready for agents.",    "metrics": { "views": 248900, "likes": 18420, "comments": 921, "shares": 338 },    "author": { "id": "creator_123", "handle": "openai" }  },  "source": { "provider": "socialcues", "endpoint": "tiktok.post.fetch" },  "usage": { "billable_units": 1, "cached": true }}
200 · post

Search posts

GET/v1/{platform}/posts/search

Search a platform's posts by keyword.

FieldInTypeDescription
platformrequiredpathenumPlatform slug.
qrequiredquerystringThe search query.
limitdefault 20queryintegerResults per page, 1–50.
cursorquerystringPagination cursor from a previous page.
sortqueryenumOrder results (platform-specific). TikTok: relevance, likes. YouTube: relevance, recent, views, rating. Twitter: top, latest.
withinqueryenumTime window (platform-specific). TikTok: day, week, month, quarter, halfyear. YouTube: hour, day, week, month, year.
lengthqueryenumYouTube only — short, medium, long.
typequeryenumYouTube only — video, channel, playlist.
regiondefault USquerystringTikTok only — 2-letter country code. Invalid values return 400; applied filters echo in source.filters_applied.

Request

curl "https://api.socialiq.dev/v1/tiktok/posts/search?q=ai%20agent%20workflows&limit=3" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_c3d4e5f6a7b8c9d0e1f2",  "data": {    "query": "ai agent workflows",    "results": [      { "id": "tiktok_posts_1", "platform": "tiktok", "type": "post",        "text": "ai agent workflows result 1",        "metrics": { "views": 10000, "engagement_rate": 0.041 } }    ]  },  "page": { "next_cursor": "c2_eyJvIjoyMH0", "has_more": true }}
200 · search

List comments

GET/v1/{platform}/posts/{id}/comments

Page through the comments on a post.

FieldInTypeDescription
platformrequiredpathenumPlatform slug.
idrequiredpathstringThe post ID.
limitdefault 20queryintegerItems per page, 1–50.
cursorquerystringPagination cursor.

Request

curl "https://api.socialiq.dev/v1/tiktok/posts/7350810998023949599/comments?limit=3" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_d4e5f6a7b8c9d0e1f2a3",  "data": {    "items": [      { "id": "comment_1", "text": "First!", "author": { "handle": "fan_01" }, "likes": 32 },      { "id": "comment_2", "text": "agent workflows ftw", "author": { "handle": "dev_22" }, "likes": 11 }    ]  },  "page": { "next_cursor": "c2_eyJvIjozfQ", "has_more": true }}
200 · comments

List reposters

GET/v1/{platform}/posts/{id}/reposts

Profiles that reposted / retweeted a post.

FieldInTypeDescription
platformrequiredpathenumPlatform slug (currently Twitter/X).
idrequiredpathstringThe post ID.
limitdefault 20queryintegerItems per page, 1–50.
cursorquerystringPagination cursor.

Request

curl "https://api.socialiq.dev/v1/twitter/posts/1750000000000000000/reposts?limit=3" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_aa11bb22cc33dd44ee55",  "data": {    "collection": "post.reposters",    "items": [      { "id": "44196397", "platform": "twitter", "type": "profile", "handle": "elonmusk", "metrics": { "followers": 200000000 } }    ]  },  "page": { "cursor": "c-1", "has_more": true }}
200 · reposters

Related posts

GET/v1/{platform}/posts/{id}/related

List posts the platform recommends alongside this one.

FieldInTypeDescription
platformrequiredpathenumPlatform slug.
idrequiredpathstringThe post ID.
limitdefault 20queryintegerItems per page, 1–50.

Request

curl "https://api.socialiq.dev/v1/tiktok/posts/7350810998023949599/related?limit=3" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_e1f2a3b4c5d6e7f8a9b0",  "data": {    "items": [      { "id": "7350900000000000001", "platform": "tiktok", "type": "post", "text": "Related clip 1" }    ]  },  "page": { "next_cursor": "c2_eyJvIjozfQ", "has_more": true }}
200 · related

Get media

GET/v1/{platform}/posts/{id}/media

Resolve download URLs, playback streams, captions, subtitles, and thumbnails.

FieldInTypeDescription
platformrequiredpathenumPlatform slug.
idrequiredpathstringThe post / media ID.
kinddefault "download"queryenumdownload, playback, captions, subtitles, thumbnail, or streams.

Request

curl "https://api.socialiq.dev/v1/youtube/posts/dQw4w9WgXcQ/media?kind=streams" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_e5f6a7b8c9d0e1f2a3b4",  "data": {    "id": "dQw4w9WgXcQ",    "platform": "youtube",    "kind": "streams",    "assets": [      { "type": "streams", "url": "https://cdn.socialiq.dev/mock/social-video.mp4", "mime_type": "video/mp4" }    ]  }}
200 · media

Post analytics

GET/v1/{platform}/posts/{id}/analytics

Provider-backed metrics for a post — views, likes, comments, and 14-day deltas (currently TikTok).

FieldInTypeDescription
platformrequiredpathenumPlatform slug (currently TikTok).
idrequiredpathstringThe post ID.

Request

curl "https://api.socialiq.dev/v1/tiktok/posts/7350810998023949599/analytics" \  -H "Authorization: Bearer sc_live_..."

Response

[ .JSON ]
{  "request_id": "sc_f6a7b8c9d0e1f2a3b4c5",  "data": {    "item_id": "7350810998023949599",    "video_views": 248900,    "likes": 18420,    "comments": 921,    "video_views_14_days": 41200  }}
200 · analytics