Introduction
What the API does, and how to make your first call.
For AI agents: use llms.txt for an index of the docs, or docs.md for all of it in one Markdown file.
The ScanSocial API gives you the public history and performance of any account and post on Instagram, TikTok, YouTube and X. Every endpoint shares one base URL, https://scansocial.com/api/v1, one key in the x-api-key header, and the response format described in these guides.
Features
Quickstart
Track your first account and read its posts in about five minutes.
- 1
Create a key
Sign up and copy your key from the console. Every new account gets a key straight away on the free start, with no card needed. The key is shown once and starts with
sd_. Keep it on your server in an environment variable, and never put it in browser code. - 2
Check it works
GET /v1/planconfirms the key works and returns your plan, its room and your request limit. - 3
Track an account
Send its profile link to
POST /v1/accounts/track. We collect its whole history and keep it in sync from then on. Itsstatusgoes fromcollectingtosyncingtotracked. - 4
Read its posts
Once it is tracked,
GET /v1/postsreturns every post it has made with the latest numbers, alongside everything else you track. Reading what you track is free.
Authentication
The base URL is https://scansocial.com/api/v1. Send your key with every request in either of these headers.
x-api-key: sd_live_…- The default. Every example on this site uses it.
Authorization: Bearer sd_live_…- For clients and gateways that only forward the standard header.
- Each key belongs to one account. All keys on an account share its plan and its room.
- Use one key per service or environment, so you can revoke one without breaking the others. The console shows usage per key.
- A missing or invalid key returns
401 unauthorized.
Responses
The body is the result itself, with no wrapper. Lists come back under a named field. Rate limit details are in the headers.
accounts,posts,results- The list of items. The main reads use a named field. Other calls use
results. pagination- On paged lists. See Pagination.
status- On calls that take ids or links, every item you name comes back, in the order you named it, with its own
status:tracked: you track it and it is readable.syncing: you track it, but it isn't readable yet.GET /v1/accountsorGET /v1/postsshows when it is.not_tracked: you don't track it. Track it withPOST /v1/accounts/trackorPOST /v1/posts/track.
limited- On the free plan, a posts read that shows fewer posts than we hold carries
"limited": true. Counts and pagination totals still report everything held. lastSyncedAt- On every account, post and comment: when it last synced. See How syncing works.
| Header | Meaning |
|---|---|
x-request-id | Quote it to support when something looks wrong |
x-ratelimit-limit, -remaining, -reset | Requests allowed per minute, requests left, and seconds until the limit resets |
Plans and room
There is one kind of plan, sized by accounts. It holds room for the accounts and posts you track, and everything you track is free to read.
- Room is counted in accounts. One account takes the room of 100 posts, so a plan holds accounts, single posts or a mix.
- Every plan includes full history, syncing and the comments under every post you track.
- A track call uses room from when it is sent. A failed collection gives the room back.
- A track call that would go past your plan returns
402 tracking_fulland tracks nothing. - Delete what you track with
POST /v1/accounts/deleteorPOST /v1/posts/delete. Items that failed or are still collecting free their room at once. Collected items free it 30 days after they were sent. GET /v1/planshows the room you hold, what is used and what is available.
- The free start
- Every account starts on it, with a key straight away and no card. You can track 3 accounts and 10 posts, as two separate caps. We collect and sync every post you track, while the reads show the latest 50 posts per account. Comments come with the paid plans, so on the free start
GET /v1/commentsreturns403 plan_required. Upgrading to any paid plan unlocks every post at once and starts collecting comments. - Enterprise
- For whole industries at scale: room agreed with you, the search calls over an index of 100M+ posts, tracked or not, and a dedicated contact. On any other plan the search calls return
403 plan_required. Book a call to set it up.
How syncing works
We run the collection, the scheduling, the retries and the history, so what you track stays current without any work on your side.
- Something new
- A new account or post shows its progress in its
status:collectingwhile we collect it,syncingon its way into the reads, thentracked.GET /v1/accountsandGET /v1/postslist it at every step. lastSyncedAt- Every account, post and comment carries the time of its latest sync.
Pagination
Lists take page and pageSize, and return a pagination object.
page- The page to return, starting at 1.
pageSize- Items per page. The default is 100, or 25 on the search calls. Each endpoint lists its maximum in the reference.
pagination- Returns
page,pageSize,count(items on this page) andtotal(items across all pages).
- There is another page while
page × pageSizeis less thantotal. posts/{id}/historypages the post's readings, up to 1,000 a page.
Rate limits
Each plan allows a number of requests per minute, per account. Every endpoint counts toward the limit.
- Over the limit, calls return
429 rate_limited. - Wait the number of seconds in the
retry-afterheader, then retry.
Errors
Every error has the shape { error: { code, message, outcome, retryable, requestId } }.
- Branch on
code. - Show
messageto people. - Retry only when
retryableistrue.
Coverage and naming
What each kind of call can reach, and how to name accounts, posts and comments.
- Tracked reads
- Calls:
GET /v1/accounts,GET /v1/posts,GET /v1/statswith itstimelineanddistribution, andGET /v1/comments, and the reads of one item underaccounts/{id}andposts/{id}, such asposts/{id}/history. GET /v1/posts,stats/distributionandGET /v1/commentsread everything you track when you name nothing. Sendaccountsorpoststo narrow them.- They read only what you track, in full, at any view count. Track an account or post before you read it.
- Every item you name comes back with its status. Anything you don't track has
status: not_trackedand no data. - The reads of one item return
404 not_foundfor anything you don't track. - An item still syncing has
status: syncing.GET /v1/accountsandGET /v1/postsshow its row. The other reads return it with no data yet. - When every item a call asks for is syncing, the other reads return
409 not_ready, which is retryable. - To find posts or comments by words within what you track, send
searchtoGET /v1/postsandstats/timeline, orqtoGET /v1/comments.
- Calls:
- Search
- Calls:
search/posts,search/tags,search/timeline,search/accountsandsearch/accounts/by-content. - Covers an index of 100M+ posts on Instagram, TikTok, YouTube and X, tracked or not: posts with over 1,000 views from the last year, and the accounts behind them.
- Comes with Enterprise. On any other plan these calls return
403 plan_required.
- Calls:
- Naming accounts
- On
GET /v1/accounts,GET /v1/stats/distribution,GET /v1/commentsand the delete calls, use ids: platform and platform account id together, such asaccounts=instagram:19237590,tiktok:6872391. One call can mix platforms. GET /v1/accounts/{id}reads one account by its id in the path, such as/v1/accounts/instagram:19237590. The path takes an id only, not a link or a platform id.- On other calls, use
platformandplatformAccountId, one platform per call, such asplatform=instagram&accounts=19237590. - Find an account to track with
GET /v1/accounts/lookup, which matches handles, names and profile links and is free on every plan. - For an account we don't hold yet, send its profile link to
POST /v1/accounts/track.
- On
- Naming posts
- On
GET /v1/posts,GET /v1/stats/distribution,GET /v1/commentsand the delete calls, use ids, such asposts=instagram:3998372802810043130_17852024998, or links inurlswhere the call takes them. - On other calls, use
platformPostIdwithplatform, or links. - Platform ids are one platform per call. Ids and links can mix platforms.
GET /v1/posts/{id},GET /v1/posts/{id}/historyandGET /v1/posts/{id}/commentsread one post by its id in the path, such as/v1/posts/instagram:3977858905957226656_1471684166. The path takes an id only.
- On
- Comments
GET /v1/commentsreads the comments on what you track, by post ids or by account ids. They come back grouped by post, each group with the post'sid, itsstatusandcommentsHeld.- Each comment has its own
id, and the ids of its post and the post's account inpostandaccount, so it joins straight back to the other reads.
- Tracking
- Track by link with
POST /v1/accounts/trackorPOST /v1/posts/track. Each returns a row per item with its id (once collected), link, platform id and status. A post's row also has its account's id inaccountonce tracked. - Status goes from
collectingtosyncingtotracked, or tofailed. Syncing means collected and on its way into the reads. That takes seconds, sometimes up to an hour. - Each item uses room on your plan from when it is sent. A failed collection gives the room back.
- One account uses the room of 100 posts.
GET /v1/planshows the room used and available. - What you track stays in sync and is free to read, at any view count or age, with the comments under it.
- An account's
postsfield says how many of its posts the reads hold. - One tracked account's read includes its demographics where we hold them. The list adds them with
includeDemographics=true. We hold none for X. - Check status with
GET /v1/accountsorGET /v1/posts. With no ids, they list everything you track on every platform, newest first, filtered bystatusandplatform. Sending the same link again also returns its status. - A failed row keeps its
erroruntil you delete it or track the link again. It clears itself after 30 days. - Delete with
POST /v1/accounts/deleteorPOST /v1/posts/delete, by id or by link. Items that failed or are still collecting free their room at once. Collected items keep their room until 30 days after they were sent, androomFreesAtsays when.
- Track by link with
- Metrics
viewsis the view count. Where the platform hides it, the post hasestimatedViewsinstead, worked out from likes.
Filter values
Every value the filters and sorts accept. Use it to build pickers or an agent's tool schema. Send several values comma-separated, such as postTypes=clips,feed.
Build with AI
Hand the whole API to a model or an agent: the docs come as plain text, written to be read in one go.
- llms.txt
- An index of the docs and every endpoint, in the llms.txt format agents look for at a site's root.
- docs.md
- The full documentation in one Markdown file: these guides, the plans, errors and filter values, and every endpoint with its parameters and an example request.
- Copy page
- The button at the top of the docs copies that Markdown, ready to paste into a chat or an agent's context.