Skip to content
DatasetsDocsPricing
Using the API

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. 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. 2

    Check it works

    GET /v1/plan confirms the key works and returns your plan, its room and your request limit.

  3. 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. Its status goes from collecting to syncing to tracked.

  4. 4

    Read its posts

    Once it is tracked, GET /v1/posts returns 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/accounts or GET /v1/posts shows when it is.
  • not_tracked: you don't track it. Track it with POST /v1/accounts/track or POST /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.
HeaderMeaning
x-request-idQuote it to support when something looks wrong
x-ratelimit-limit, -remaining, -resetRequests 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_full and tracks nothing.
  • Delete what you track with POST /v1/accounts/delete or POST /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/plan shows 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/comments returns 403 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: collecting while we collect it, syncing on its way into the reads, then tracked. GET /v1/accounts and GET /v1/posts list 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) and total (items across all pages).
  • There is another page while page × pageSize is less than total.
  • posts/{id}/history pages 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-after header, then retry.

Errors

Every error has the shape { error: { code, message, outcome, retryable, requestId } }.

  • Branch on code.
  • Show message to people.
  • Retry only when retryable is true.

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/stats with its timeline and distribution, and GET /v1/comments, and the reads of one item under accounts/{id} and posts/{id}, such as posts/{id}/history.
  • GET /v1/posts, stats/distribution and GET /v1/comments read everything you track when you name nothing. Send accounts or posts to 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_tracked and no data.
  • The reads of one item return 404 not_found for anything you don't track.
  • An item still syncing has status: syncing. GET /v1/accounts and GET /v1/posts show 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 search to GET /v1/posts and stats/timeline, or q to GET /v1/comments.
Search
  • Calls: search/posts, search/tags, search/timeline, search/accounts and search/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.
Naming accounts
  • On GET /v1/accounts, GET /v1/stats/distribution, GET /v1/comments and the delete calls, use ids: platform and platform account id together, such as accounts=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 platform and platformAccountId, one platform per call, such as platform=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.
Naming posts
  • On GET /v1/posts, GET /v1/stats/distribution, GET /v1/comments and the delete calls, use ids, such as posts=instagram:3998372802810043130_17852024998, or links in urls where the call takes them.
  • On other calls, use platformPostId with platform, or links.
  • Platform ids are one platform per call. Ids and links can mix platforms.
  • GET /v1/posts/{id}, GET /v1/posts/{id}/history and GET /v1/posts/{id}/comments read one post by its id in the path, such as /v1/posts/instagram:3977858905957226656_1471684166. The path takes an id only.
Comments
  • GET /v1/comments reads the comments on what you track, by post ids or by account ids. They come back grouped by post, each group with the post's id, its status and commentsHeld.
  • Each comment has its own id, and the ids of its post and the post's account in post and account, so it joins straight back to the other reads.
Tracking
  • Track by link with POST /v1/accounts/track or POST /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 in account once tracked.
  • Status goes from collecting to syncing to tracked, or to failed. 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/plan shows 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 posts field 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/accounts or GET /v1/posts. With no ids, they list everything you track on every platform, newest first, filtered by status and platform. Sending the same link again also returns its status.
  • A failed row keeps its error until you delete it or track the link again. It clears itself after 30 days.
  • Delete with POST /v1/accounts/delete or POST /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, and roomFreesAt says when.
Metrics
  • views is the view count. Where the platform hides it, the post has estimatedViews instead, 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.