API Reference

Endpoints

ScanSocial API (v1)

For AI agents: use llms.txt for an index of the docs, or docs.md for every endpoint in one Markdown file.

Every call goes to https://scansocial.com/api/v1 with your key in the x-api-key header, and answers in the format the guides describe. New here? Start with the quickstart.

Accounts

Track accounts, then read their profiles and posts, free, across their whole history, or delete them. Find one to track with GET /v1/accounts/lookup. Anything you don't track comes back with status not_tracked.

POST/v1/accounts/track

Track accounts

Starts collecting accounts, including ones we don't hold yet, and keeps collecting them on our regular schedule. Send each account's link. Each comes back as the row GET /v1/accounts gives it: id (as instagram:19237590, null until collected), url, platform, platformAccountId, status, the profile once tracked, posts (how many of its posts the tracked reads hold), postsInSearch, lastSyncedAt and error. Once the first collection finishes, this key reads its whole history at any views from GET /v1/posts, the stats endpoints, /v1/posts/{id}/history and /v1/comments. lastSyncedAt is the time of its latest sync. Search (Enterprise) and /v1/search/timeline only cover posts with over 1,000 views in the last year, after the next hourly refresh; postsInSearch says how many those are. status is collecting while we collect it, syncing once collected while it reaches the tracked reads (seconds, sometimes up to an hour), then tracked, or failed. It stays tracked from then on. Until it is tracked, every read returns it with its status. Sending a link again changes nothing, costs nothing more and returns its latest status. Each one takes room on your plan from when it is sent, and a failed collection gives it back. One account takes the room of 100 posts; Free holds 3 accounts and 10 posts, as two separate caps. When a call would go past the plan, nothing in it is tracked and it returns 402 tracking_full with what is used and available. Delete anything you track with POST /v1/accounts/delete or POST /v1/posts/delete; something collected keeps its room until 30 days after it was sent. Reading what you track is free.

your planUses 1 account of your plan
Parameters
ParameterDetails
urls
bodyjsonrequired

Account links, up to 25.

Try it in the playground →
Response
POST/v1/accounts/delete

Delete tracked accounts

Stops tracking what these ids or links name, whatever its status, failed included. Each comes back with its id (null if it was still collecting), url, status deleted and roomFreesAt. Something still collecting, or failed, gives its room back at once, and roomFreesAt is null. Something collected keeps its room until 30 days after it was sent, and roomFreesAt says when it frees; after that it frees at once. Deleting an account also stops the posts tracked only through it; posts you tracked on their own stay. Anything this key didn't send to track comes back with status not_tracked, and nothing changes for it. tracking is your plan's room after the call. Once deleted, the reads return it with status not_tracked. Tracking it again later is like any other track, and its history is still there.

freeFree

Frees the room the account used.

Parameters
ParameterDetails
ids
bodyjson

Ids, as GET /v1/accounts gives them, up to 25 with urls, mixed platforms allowed. A platform id works when platform is sent.

urls
bodyjson

Links, as sent to POST /v1/accounts/track.

platform
bodyenum

The platform of any bare ids.

instagram tiktok youtube x facebook linkedin snapchat
Try it in the playground →
Response
GET/v1/accounts/lookup

Find an account to track

Up to 10 accounts on Instagram, TikTok, YouTube and X that match q, searched on the platforms themselves, or the account behind a pasted profile link, for picking what to send to POST /v1/accounts/track. Any public account can come back, tracked or not. Each has platform, url, username, displayName, avatarUrl, followers, and tracked: whether this key tracks it already. A profile link comes back as one candidate; where we have never collected it, only platform, url and username are set, read from the link. Track any of them by its url and we collect it.

freeFree
Parameters
ParameterDetails
q
querystringrequired

Words in a handle or display name, or a profile link.

platform
queryenum

Only accounts on this platform.

instagram tiktok youtube x facebook linkedin snapchat
Try it in the playground →
Response
GET/v1/accounts

Accounts you track

Everything you track, or the accounts you name, across every platform. With no ids or urls, it lists every account this key has sent to POST /v1/accounts/track, newest first, paged, and status and platform filter the list. With ids, it reads those: each an id, the platform and its platform account id, as instagram:19237590, mixed platforms allowed. A platform id works when platform is sent too. urls names accounts by the link sent to track them. Each account you name comes back as one row, in the order named: id (null until collected), url, platform, platformAccountId, status, then the profile once tracked (username, displayName, avatarUrl and followers), posts, postsInSearch, lastSyncedAt and error. The profile is null while it is collecting or syncing. A failed row keeps its error until you delete it or track the link again. No post numbers: GET /v1/stats and its timeline give those for any dates. Anything you don't track comes back with status not_tracked and every other field null. Partial results are always a 200. includeDemographics=true adds each profile's demographics where we hold them; GET /v1/accounts/{id} always has them. An account this key tracks has demographics: gender by age, countries, interests and brand affinity. Any other account has no demographics field. Nor does a tracked account we hold none for, which includes every X, Facebook, LinkedIn and Snapchat account. Filtering or sorting by audience only finds accounts this key tracks.

freeFree

Free for accounts you track.

Parameters
ParameterDetails
ids
querystring

Comma-separated ids, the platform and its own id together, up to 100 with urls, mixed platforms allowed. A platform id works when platform is sent.

urls
querystring

Comma-separated profile links, as sent to POST /v1/accounts/track.

includeDemographics
querybool

true adds each tracked account's demographics where we hold them.

platform
queryenum

Only accounts on this platform. With bare ids, the platform they are on.

instagram tiktok youtube x facebook linkedin snapchat
status
queryenum

Only rows in this status.

collecting syncing tracked failed not_tracked
page
queryint

Which page, from 1.

Default 1
pageSize
queryint

Accounts a page when listing, up to 1000.

Default 100
Try it in the playground →
Response
GET/v1/accounts/{id}

An account you track

One account you track, by its id, as instagram:19237590: the row GET /v1/accounts gives it, with id, url, platform, platformAccountId, status, the profile once tracked with its demographics where we hold them, posts, postsInSearch, lastSyncedAt and error. While it is collecting or syncing it comes back with that status and no profile yet. Anything you don't track returns 404 not_found.

freeFree

Free for accounts you track.

Parameters
ParameterDetails
id
pathstringrequired

The account's id, the platform and its own id together, as instagram:19237590.

Try it in the playground →
Response

Stats

The numbers for everything you track, or the accounts or posts you name, for any filters, free: added up into one set of figures, over time, or split by platform, account or post type. Every call takes the same scope and filters.

GET/v1/stats

Stats for any filters

Everything you track, or the accounts or posts you name, added up into one set of figures: the numbers an analytics overview leads with, in one call, with no series and no groups. stats has posts, accounts, views, plays, likes, comments, shares, saves and reposts for the posts that match, the average and median post's views, likes and comments. Filter by post type, words, views and dates as on GET /v1/posts. Stories are left out. A collaboration between accounts you send counts once. With no dates it covers each account's whole history. Every post or account you name comes back with its status: tracked, syncing or not_tracked, and the numbers cover the tracked ones. When every one you name is syncing, the call returns 409 not_ready. Numbers are the app's analytics figures: views are plays, or the estimate where the platform hides them, likes are 0 where hidden, and reposts include quotes.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
accounts
querystring

Comma-separated account ids, as instagram:19237590, up to 100, mixed platforms allowed. A platform id works when platform is sent. Only their posts.

posts
querystring

Comma-separated post ids, as instagram:3977858905957226656_1471684166, up to 100, mixed platforms allowed: only these posts, such as a campaign's. A platform id works when platform is sent. Send posts or accounts, or neither for everything.

platform
queryenum

The platform of any platform ids in posts or accounts.

instagram tiktok youtube x facebook linkedin snapchat
postTypes
querystring

Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote.

search
querystring

Only posts with these words in the caption, title, hashtags or mentions.

minViews
queryint

From 0: every post counts.

maxViews
queryint
postedWithinDays
queryint

Days back, with no upper limit.

fromDate
querystring

The first day, YYYY-MM-DD, UTC. Inclusive.

toDate
querystring

The last day, YYYY-MM-DD, UTC. Inclusive.

Try it in the playground →
Response
GET/v1/stats/timeline

Stats over time

Everything you track, or the accounts or posts you name, per day, week or month, across their whole history at any views: the posts made and their views, plays, likes, comments, shares, saves and reposts, plus totals for the whole period. Each point has date, the start of its bucket. The metrics sit on the bucket a post went up in, at their current totals. With no dates set, the series runs from the first post to today. groupBy=account splits the same posts by account, each with its own totals and series, and the response has the overall totals but no overall series. A named account with no posts in the period still gets a group. A collaboration between accounts you send counts once, or for each account when grouped by account. Filter by post type, words, views and dates as on GET /v1/posts. Stories are left out. Every post or account you name comes back with its status: tracked, syncing or not_tracked, and the numbers cover the tracked ones. When every one you name is syncing, the call returns 409 not_ready. Numbers are the app's analytics figures: views are plays, or the estimate where the platform hides them, likes are 0 where hidden, and reposts include quotes.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
platform
queryenum

The platform of any platform ids in posts or accounts.

instagram tiktok youtube x facebook linkedin snapchat
accounts
querystring

Comma-separated account ids, as instagram:19237590, up to 100, mixed platforms allowed. A platform id works when platform is sent. Only their posts.

posts
querystring

Comma-separated post ids, as instagram:3977858905957226656_1471684166, up to 100, mixed platforms allowed: only these posts, such as a campaign's. A platform id works when platform is sent. Send posts or accounts, or neither for everything.

bucket
queryenum
day week month
Default month
groupBy
queryenum

Split the posts by account, each with its own totals and series.

account
groupLimit
queryint

How many account groups to return. Defaults to 10.

groupSort
queryenum

Which metric picks and orders the groups.

posts views likes comments shares saves reposts
Default posts
postTypes
querystring

Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote.

search
querystring

Only posts with these words in the caption, title, hashtags or mentions.

minViews
queryint

From 0: every post counts.

maxViews
queryint
postedWithinDays
queryint

Days back, with no upper limit.

fromDate
querystring

The first day, YYYY-MM-DD, UTC. Inclusive.

toDate
querystring

The last day, YYYY-MM-DD, UTC. Inclusive.

Try it in the playground →
Response
GET/v1/stats/distribution

Stats split by platform, account or post type

Everything you track, or the posts or accounts you name, added up by platform, account or post type: how the numbers split, in one call. by=platform gives a group per platform, by=account one per account with its id and profile, and by=postType one per platform and post type, as instagram:clips or tiktok:video, since each platform has its own types. Every group has key, its totals (posts, accounts, views, plays, likes, comments, shares, saves and reposts) and share, its part of the overall views from 0 to 1. totals adds up every post, so naming a campaign's posts gives its end-of-campaign totals and how they split. By account, a collaboration counts for each account in it, so the shares can add up past 1. Filter by post type, words, views and dates as on GET /v1/posts. Stories are left out. Groups are sorted by sort, and limit caps how many come back; groupsTotal says how many there are. Every post or account you name comes back with its status: tracked, syncing or not_tracked, and the numbers cover the tracked ones. When every one you name is syncing, the call returns 409 not_ready. Numbers are the app's analytics figures: views are plays, or the estimate where the platform hides them, likes are 0 where hidden, and reposts include quotes.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
by
queryenumrequired

What to add the posts up by.

platform account postType
posts
querystring

Comma-separated post ids, as instagram:3977858905957226656_1471684166, up to 50, mixed platforms allowed: only these posts, such as a campaign's. A platform id works when platform is sent. Send posts or accounts, or neither for everything.

accounts
querystring

Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when platform is sent. Only their posts.

platform
queryenum

The platform of any platform ids in posts or accounts.

instagram tiktok youtube x facebook linkedin snapchat
sort
queryenum

Which figure orders the groups, highest first.

posts views likes comments shares saves reposts
Default views
limit
queryint

How many groups to return, up to 100.

Default 50
postTypes
querystring

Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote.

search
querystring

Only posts with these words in the caption, title, hashtags or mentions.

minViews
queryint

From 0: every post counts.

maxViews
queryint
postedWithinDays
queryint

Days back, with no upper limit.

fromDate
querystring

The first day, YYYY-MM-DD, UTC. Inclusive.

toDate
querystring

The last day, YYYY-MM-DD, UTC. Inclusive.

Try it in the playground →
Response

Posts

Track single posts, then read them and their history, free, at any views or age, or delete them. A post counts as tracked directly or through its account. Anything else comes back with status not_tracked.

POST/v1/posts/track

Track single posts

Starts collecting single posts without tracking their accounts, and keeps their numbers updating on our regular schedule. Send each post's link. Each comes back as the row GET /v1/posts gives it: id (null until collected), url, platform, platformPostId, account (its account's id), status, the post's record once tracked, inSearch, lastSyncedAt and error. inSearch says whether it has reached search (Enterprise), which only includes posts with over 1,000 views. status is collecting while we collect it, syncing once collected while it reaches the tracked reads (seconds, sometimes up to an hour), then tracked, or failed. It stays tracked from then on. Until it is tracked, every read returns it with its status. Sending a link again changes nothing, costs nothing more and returns its latest status. Each one takes room on your plan from when it is sent, and a failed collection gives it back. One account takes the room of 100 posts; Free holds 3 accounts and 10 posts, as two separate caps. When a call would go past the plan, nothing in it is tracked and it returns 402 tracking_full with what is used and available. Delete anything you track with POST /v1/accounts/delete or POST /v1/posts/delete; something collected keeps its room until 30 days after it was sent. Reading what you track is free.

your planUses 1 post of your plan, 1/100 of an account
Parameters
ParameterDetails
urls
bodyjsonrequired

Post links, up to 25.

Try it in the playground →
Response
POST/v1/posts/delete

Delete tracked posts

Stops tracking what these ids or links name, whatever its status, failed included. Each comes back with its id (null if it was still collecting), url, status deleted and roomFreesAt. Something still collecting, or failed, gives its room back at once, and roomFreesAt is null. Something collected keeps its room until 30 days after it was sent, and roomFreesAt says when it frees; after that it frees at once. Anything this key didn't send to track comes back with status not_tracked, and nothing changes for it. tracking is your plan's room after the call. Once deleted, the reads return it with status not_tracked. Tracking it again later is like any other track, and its history is still there.

freeFree

Frees the room the post used.

Parameters
ParameterDetails
ids
bodyjson

Ids, as GET /v1/posts gives them, up to 25 with urls, mixed platforms allowed. A platform id works when platform is sent.

urls
bodyjson

Links, as sent to POST /v1/posts/track.

platform
bodyenum

The platform of any bare ids.

instagram tiktok youtube x facebook linkedin snapchat
Try it in the playground →
Response
GET/v1/posts

Posts you track

Every post you track, tracked on its own or through its account, across every platform: the one call for posts. With nothing named, it pages through all of them, stories included, newest first, at any views or age with their latest numbers. accounts narrows it to those accounts' posts and lists each with its status: tracked, syncing or not_tracked; when every one is syncing, the call returns 409 not_ready. singlePostsOnly=true lists only the posts tracked on their own, none from an account you track. Filter by platform, post type, words, views and dates, and sort by any figure, recent or oldest. ids or urls instead reads the posts you name, one row each in the order named, whatever their status, and anything you don't track comes back not_tracked with every other field null. status collecting, syncing or failed lists what you sent to POST /v1/posts/track that isn't tracked yet. Every row has id (null until collected), url, platform, platformPostId, account (its account's id), status, then its record once tracked, the app's analytics figures: views, plays, likes, comments, shares, saves and reposts. Then inSearch, lastSyncedAt and error. Views are plays, or the estimate where the platform hides them, likes are 0 where hidden, and reposts include quotes. On Free, only each account's latest 50 posts are shown, plus, when sorted by a figure, the top page by that figure across every post held. pagination.total still counts every post held, and limited is true when any were held back.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
accounts
querystring

Comma-separated account ids, as instagram:19237590, up to 100, mixed platforms allowed. A platform id works when platform is sent. Only their posts.

singlePostsOnly
querybool

true lists only the posts tracked on their own, none from an account you track.

platform
queryenum

Only posts on this platform. With bare ids, the platform they are on.

instagram tiktok youtube x facebook linkedin snapchat
sort
queryenum
recent oldest views plays likes comments shares saves reposts
Default recent
postTypes
querystring

Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote.

search
querystring

Only posts with these words in the caption, title, hashtags or mentions.

minViews
queryint

From 0: every post counts.

maxViews
queryint
postedWithinDays
queryint

Days back, with no upper limit.

fromDate
querystring

The first day, YYYY-MM-DD, UTC. Inclusive.

toDate
querystring

The last day, YYYY-MM-DD, UTC. Inclusive.

ids
querystring

Comma-separated ids, the platform and its own id together, up to 100 with urls, mixed platforms allowed. A platform id works when platform is sent.

urls
querystring

Comma-separated post links.

status
queryenum

Only rows in this status.

collecting syncing tracked failed not_tracked
page
queryint

Which page, from 1.

Default 1
pageSize
queryint

Posts a page when listing, up to 1000.

Default 100
Try it in the playground →
Response
GET/v1/posts/{id}

A post you track

One post you track, directly or through its account, by its id, as instagram:3977858905957226656_1471684166: the row GET /v1/posts gives it, with id, url, platform, platformPostId, account (its account's id), status, its record once tracked, inSearch, lastSyncedAt and error. Anything you don't track returns 404 not_found.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
id
pathstringrequired

The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166.

Try it in the playground →
Response
GET/v1/posts/{id}/history

One post's readings over time

Every reading taken of one post you track, directly or through its account, oldest first: views, likes, comments, shares, saves and reposts at each date. A post can be read several times a day, and posts from one account read together share a timestamp. A reading has views, or estimatedViews instead where the platform hides the count and we work it out from likes. Draws how a post grew and when it stalled. It comes back with the post's id, platform, platformPostId, url and status. A count that reads 0 between two readings above it is a missed read, so it carries the last count instead. page and pageSize page the readings. Anything you don't track returns 404 not_found, and a post still syncing returns 409 not_ready.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
id
pathstringrequired

The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166.

page
queryint

Which page, from 1.

Default 1
pageSize
queryint

Readings a page, up to 1000.

Default 200
Try it in the playground →
Response

Comments

The comments under everything you track, collected and kept syncing as part of tracking. Read them by post or by account, free, as often as you like.

GET/v1/comments

The comments on what you track

The comments we hold under the posts this key tracks, directly or through their account, collected and kept syncing as part of tracking: the one call for comments. On tracking, the comments of posts from the last 30 days are collected; then posts from the last 7 days get theirs once a day and posts 7 to 30 days old once a week. With nothing named, it reads the comments across everything you track. Name posts by id (up to 50, mixed platforms) or accounts by id (up to 25) to narrow it to theirs. Each comment has its id, post and account (their ids), platform, author (username, displayName, avatarUrl), text, likes, replies, publishedAt and lastSyncedAt. They come grouped by post, each group with its post's id, status (tracked, syncing or not_tracked), commentsHeld, how many we hold on it, and the post's caption, thumbnailUrl, postedAt and accountUsername (null unless tracked). Every post you name gets a group, in the order named; otherwise, a group for each post with comments on this page. sort is recent or likes; since and until narrow by when each was written; q keeps comments with every one of its words. page and pageSize page across all the posts together, so pagination.total is every comment that matches. Comments come with every paid plan: on Free this call returns 403 plan_required. When every post or account you name is syncing, the call returns 409 not_ready.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
posts
querystring

Comma-separated post ids, as instagram:3977858905957226656_1471684166, up to 50, mixed platforms allowed. A platform id works when platform is sent.

accounts
querystring

Comma-separated account ids, as instagram:19237590, up to 25, mixed platforms allowed: the comments across their posts. A platform id works when platform is sent. Send posts or accounts, or neither for everything.

platform
queryenum

The platform of any platform ids.

instagram tiktok youtube x facebook linkedin snapchat
sort
queryenum
recent likes
Default recent
since
querystring

Only comments written from then: YYYY-MM-DD or an ISO time.

until
querystring

Only comments written up to then: YYYY-MM-DD (that whole day) or an ISO time.

q
querystring

Words the text must all have, up to 8.

page
queryint

Which page, from 1.

Default 1
pageSize
queryint

Comments a page, up to 1000.

Default 100
Try it in the playground →
Response
GET/v1/posts/{id}/comments

Comments on one post

The comments we hold on one post you track, directly or through its account, as GET /v1/comments gives them: post (its id), commentsHeld, how many we hold on it, and its comments, each with its id, post, account, platform, author, text, likes, replies, publishedAt and lastSyncedAt. sort, since, until and q work as on GET /v1/comments, and page and pageSize page the comments. Comments come with every paid plan: on Free this call returns 403 plan_required. Anything you don't track returns 404 not_found, and a post still syncing returns 409 not_ready.

freeFree

Free for posts and accounts you track.

Parameters
ParameterDetails
id
pathstringrequired

The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166.

sort
queryenum
recent likes
Default recent
since
querystring

Only comments written from then: YYYY-MM-DD or an ISO time.

until
querystring

Only comments written up to then: YYYY-MM-DD (that whole day) or an ISO time.

q
querystring

Words the text must all have, up to 8.

page
queryint

Which page, from 1.

Default 1
pageSize
queryint

Comments a page, up to 1000.

Default 100
Try it in the playground →
Response

Your plan

Your plan, tracking room, read limits and usage. Always free.

GET/v1/plan

Your plan, room and limits

Everything this key runs under in one call, and the first call to make when wiring up an integration, since it also confirms the key works. plan is the plan this key is on. tracking is its room: for accounts and for posts, the limit, what is used and what is available. On a paid plan one account takes the room of 100 posts (postsPerAccount), so the two limits are the same room counted two ways and available says how much is left either way. Something collected keeps its room until 30 days after it was sent. Free has two separate caps instead, 3 accounts and 10 posts. access says which endpoints this key can call: comments for /v1/comments (every paid plan) and search for /v1/search/* (Enterprise). limits has requestsPerMinute, the request limit, and on Free postsShown, how many of each account's latest posts its reads show.

freeFree
Parameters

No parameters.

Try it in the playground →
Response
GET/v1/usage

Requests over recent days

What this account's keys have called over the last days, as the console's usage page shows it: the total requests, each UTC day's requests oldest first, with every day in the range listed even when it had none, and each endpoint's requests, most first. Only successful requests count, and reads the ScanSocial console makes for you don't. Tracking room is on GET /v1/plan.

freeFree
Parameters
ParameterDetails
days
queryint

How many days back, today included. Up to 90.

Default 30
Try it in the playground →
Response