# ScanSocial API documentation

A managed social data API for TikTok, Instagram, YouTube and X. Name the accounts and posts you care about, and we keep them in sync: full history, numbers that keep updating and what people say under them. Reading what you track is free. Whole industries at scale, from an index of 100M+ posts, come with Enterprise. Base URL: `https://scansocial.com/api/v1`. Send your key in the `x-api-key` header. Web version: https://scansocial.com/docs

## Quickstart

Track your first account and read its posts in about five minutes.

### Step 1: Create a key

[Sign up](https://scansocial.com/dashboard?auth=signup) 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.

### Step 2: Check it works

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

### Step 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`.

### Step 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](https://scansocial.com/dashboard) 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.

| 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_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](https://scansocial.com/book-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.

| Plan | Requests per minute | Room | Price per month |
| --- | --- | --- | --- |
| Free | 60 | 3 accounts and 10 posts | $0 |
| Starter | 600 | 10 accounts or 1,000 posts | $100 |
| Growth | 1,200 | 40 accounts or 4,000 posts | $300 |
| Pro | 3,000 | 200 accounts or 20,000 posts | $1,000 |
| Scale | 6,000 | 750 accounts or 75,000 posts | $2,500 |
| Platform | 10,000 | 2,000 accounts or 200,000 posts | $5,000 |
| Enterprise | 20,000 | As agreed | From $10,000 |

## 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`.

| Status | Code | Retryable | Message |
| --- | --- | --- | --- |
| 400 | `validation_error` | No | The request is not valid. |
| 401 | `unauthorized` | No | Send a valid API key in the x-api-key header. |
| 402 | `tracking_full` | No | Your plan has no room for these. Upgrade to a bigger plan, or delete something you have tracked for 30 days or more. |
| 403 | `plan_required` | No | Search comes with Enterprise. Book a call to set it up. |
| 403 | `forbidden` | No | This key cannot do that. |
| 404 | `not_found` | No | Nothing was found. |
| 409 | `not_ready` | Yes | Tracked, and still syncing into the tracked reads. Check GET /v1/accounts or GET /v1/posts, then try again. |
| 429 | `rate_limited` | Yes | Too many requests. Wait and retry. |
| 500 | `internal` | Yes | Something went wrong on our side. |
| 502 | `upstream_failed` | Yes | A data source failed. Retry shortly. |
| 503 | `not_configured` | No | This part of the API is not configured on this deployment. |

## 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`.

| Filter | Parameter | Values | Notes | Taken by |
| --- | --- | --- | --- | --- |
| Platforms | `platforms` | `instagram`, `tiktok`, `youtube`, `x` |  | GET /v1/search/posts, GET /v1/search/accounts, GET /v1/search/accounts/by-content, GET /v1/search/timeline, GET /v1/search/tags |
| Creator categories | `categories` | `sports` (Sports), `food_beverage` (Food & Beverage), `comedy` (Entertainment), `fashion` (Fashion), `beauty` (Beauty), `health_fitness` (Health & Fitness), `travel` (Travel), `home_family` (Home & Family), `film_tv` (Film & TV), `music` (Music), `news` (News), `business` (Business), `tech_ai` (Tech & AI), `wagering` (Wagering), `gaming` (Gaming), `automotive` (Automotive), `live_events` (Live Events), `education` (Education) |  | GET /v1/search/posts, GET /v1/search/accounts, GET /v1/search/accounts/by-content, GET /v1/search/timeline |
| Account types | `accountTypes` | `brand`, `influencer`, `institution` |  | GET /v1/search/posts, GET /v1/search/accounts, GET /v1/search/accounts/by-content, GET /v1/search/timeline |
| Age bands | `ageBands` | `13-17`, `18-24`, `25-34`, `35-44`, `45-64`, `65-` | Only finds accounts this key tracks. | GET /v1/search/posts, GET /v1/search/accounts, GET /v1/search/accounts/by-content, GET /v1/search/timeline |
| Audience gender | `gender` | `female`, `male` | Only finds accounts this key tracks. | GET /v1/search/posts, GET /v1/search/accounts, GET /v1/search/accounts/by-content, GET /v1/search/timeline |
| Post search sorts | `sort` | `relevance`, `views`, `recent`, `likes`, `comments`, `outliers`, `surging` |  | GET /v1/search/posts |
| Account search sorts | `sort` | `followers`, `views`, `growth`, `country`, `female`, `male` | country, female and male only find accounts this key tracks. | GET /v1/search/accounts |
| Accounts behind a topic sorts | `sort` | `posts`, `views`, `likes`, `comments`, `followers` |  | GET /v1/search/accounts/by-content |
| Tracked post sorts | `sort` | `recent`, `oldest`, `views`, `plays`, `likes`, `comments`, `shares`, `saves`, `reposts` |  | GET /v1/posts |
| Tracked post types | `postTypes` | `clips`, `feed`, `carousel_container`, `story`, `video`, `photo`, `shorts`, `videos`, `live`, `tweet`, `reply`, `quote` | Matched exactly per platform. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote. | GET /v1/stats, GET /v1/stats/timeline, GET /v1/stats/distribution, GET /v1/posts |
| Tracking statuses | `status` | `collecting`, `syncing`, `tracked`, `failed`, `not_tracked` |  | GET /v1/accounts, GET /v1/posts |
| Timeline buckets | `bucket` | `hour`, `day`, `week`, `month` |  | GET /v1/search/timeline |
| Tracked account timeline buckets | `bucket` | `day`, `week`, `month` |  | GET /v1/stats/timeline |
| Timeline groups | `groupBy` | `platform`, `account`, `tag` |  | GET /v1/search/timeline |
| Timeline group sorts | `groupSort` | `posts`, `views`, `likes`, `comments`, `shares`, `saves`, `reposts` |  | GET /v1/stats/timeline, GET /v1/search/timeline |
| Timeline extras | `include` | `attention`, `themes` |  | GET /v1/search/timeline |
| Comment sorts | `sort` | `recent`, `likes` |  | GET /v1/comments, GET /v1/posts/{id}/comments |

## 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](https://scansocial.com/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](https://scansocial.com/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.

## API reference

Every endpoint, by group, with its parameters, what it runs on and an example request.

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

**Runs on:** Uses 1 account of your plan.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `urls` | body | json | Yes | Account links, up to 25. |

Example request:

```bash
curl -X POST "https://scansocial.com/api/v1/accounts/track" \
  -H "x-api-key: $SCANSOCIAL_KEY" \
  -H "content-type: application/json" \
  -d '{"urls":["https://www.instagram.com/kilncoffee"]}'
```

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

**Runs on:** Free. Frees the room the account used.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `ids` | body | json | No | Ids, as GET /v1/accounts gives them, up to 25 with urls, mixed platforms allowed. A platform id works when platform is sent. |
| `urls` | body | json | No | Links, as sent to POST /v1/accounts/track. |
| `platform` | body | enum | No | The platform of any bare ids. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |

Example request:

```bash
curl -X POST "https://scansocial.com/api/v1/accounts/delete" \
  -H "x-api-key: $SCANSOCIAL_KEY" \
  -H "content-type: application/json" \
  -d '{"ids":["instagram:19237590"]}'
```

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

**Runs on:** Free.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | Yes | Words in a handle or display name, or a profile link. |
| `platform` | query | enum | No | Only accounts on this platform. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/accounts/lookup?q=nhl&platform=instagram" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `ids` | query | string | No | 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` | query | string | No | Comma-separated profile links, as sent to POST /v1/accounts/track. |
| `includeDemographics` | query | bool | No | true adds each tracked account's demographics where we hold them. |
| `platform` | query | enum | No | Only accounts on this platform. With bare ids, the platform they are on. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `status` | query | enum | No | Only rows in this status. Values: `collecting`, `syncing`, `tracked`, `failed`, `not_tracked`. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Accounts a page when listing, up to 1000. Default: `100`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/accounts?ids=instagram%3A19237590%2Cinstagram%3A1471684166" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | The account's id, the platform and its own id together, as instagram:19237590. |

Example request:

```bash
curl "https://scansocial.com/api/v1/accounts/instagram:19237590" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `accounts` | query | string | No | 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` | query | string | No | 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` | query | enum | No | The platform of any platform ids in posts or accounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `postTypes` | query | string | No | Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote. |
| `search` | query | string | No | Only posts with these words in the caption, title, hashtags or mentions. |
| `minViews` | query | int | No | From 0: every post counts. |
| `maxViews` | query | int | No |  |
| `postedWithinDays` | query | int | No | Days back, with no upper limit. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |

Example request:

```bash
curl "https://scansocial.com/api/v1/stats?posts=instagram%3A3977858905957226656_1471684166%2Cinstagram%3A4024503506303021603_19237590" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `platform` | query | enum | No | The platform of any platform ids in posts or accounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `accounts` | query | string | No | 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` | query | string | No | 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` | query | enum | No | Values: `day`, `week`, `month`. Default: `month`. |
| `groupBy` | query | enum | No | Split the posts by account, each with its own totals and series. Values: `account`. |
| `groupLimit` | query | int | No | How many account groups to return. Defaults to 10. |
| `groupSort` | query | enum | No | Which metric picks and orders the groups. Values: `posts`, `views`, `likes`, `comments`, `shares`, `saves`, `reposts`. Default: `posts`. |
| `postTypes` | query | string | No | Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote. |
| `search` | query | string | No | Only posts with these words in the caption, title, hashtags or mentions. |
| `minViews` | query | int | No | From 0: every post counts. |
| `maxViews` | query | int | No |  |
| `postedWithinDays` | query | int | No | Days back, with no upper limit. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |

Example request:

```bash
curl "https://scansocial.com/api/v1/stats/timeline?accounts=instagram%3A19237590%2Cinstagram%3A1471684166&groupBy=account" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `by` | query | enum | Yes | What to add the posts up by. Values: `platform`, `account`, `postType`. |
| `posts` | query | string | No | 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` | query | string | No | 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` | query | enum | No | The platform of any platform ids in posts or accounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `sort` | query | enum | No | Which figure orders the groups, highest first. Values: `posts`, `views`, `likes`, `comments`, `shares`, `saves`, `reposts`. Default: `views`. |
| `limit` | query | int | No | How many groups to return, up to 100. Default: `50`. |
| `postTypes` | query | string | No | Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote. |
| `search` | query | string | No | Only posts with these words in the caption, title, hashtags or mentions. |
| `minViews` | query | int | No | From 0: every post counts. |
| `maxViews` | query | int | No |  |
| `postedWithinDays` | query | int | No | Days back, with no upper limit. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |

Example request:

```bash
curl "https://scansocial.com/api/v1/stats/distribution?by=account&posts=instagram%3A3977858905957226656_1471684166%2Cinstagram%3A4024503506303021603_19237590" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Uses 1 post of your plan, 1/100 of an account.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `urls` | body | json | Yes | Post links, up to 25. |

Example request:

```bash
curl -X POST "https://scansocial.com/api/v1/posts/track" \
  -H "x-api-key: $SCANSOCIAL_KEY" \
  -H "content-type: application/json" \
  -d '{"urls":["https://www.instagram.com/p/C8xTidewell"]}'
```

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

**Runs on:** Free. Frees the room the post used.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `ids` | body | json | No | Ids, as GET /v1/posts gives them, up to 25 with urls, mixed platforms allowed. A platform id works when platform is sent. |
| `urls` | body | json | No | Links, as sent to POST /v1/posts/track. |
| `platform` | body | enum | No | The platform of any bare ids. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |

Example request:

```bash
curl -X POST "https://scansocial.com/api/v1/posts/delete" \
  -H "x-api-key: $SCANSOCIAL_KEY" \
  -H "content-type: application/json" \
  -d '{"ids":["instagram:3998372802810043130_17852024998"]}'
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `accounts` | query | string | No | 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` | query | bool | No | true lists only the posts tracked on their own, none from an account you track. |
| `platform` | query | enum | No | Only posts on this platform. With bare ids, the platform they are on. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `sort` | query | enum | No | Values: `recent`, `oldest`, `views`, `plays`, `likes`, `comments`, `shares`, `saves`, `reposts`. Default: `recent`. |
| `postTypes` | query | string | No | Comma-separated post types, matched exactly. Instagram: clips, feed, carousel_container, story. TikTok: video, photo. YouTube: shorts, videos, live. X: tweet, reply, quote. |
| `search` | query | string | No | Only posts with these words in the caption, title, hashtags or mentions. |
| `minViews` | query | int | No | From 0: every post counts. |
| `maxViews` | query | int | No |  |
| `postedWithinDays` | query | int | No | Days back, with no upper limit. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |
| `ids` | query | string | No | 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` | query | string | No | Comma-separated post links. |
| `status` | query | enum | No | Only rows in this status. Values: `collecting`, `syncing`, `tracked`, `failed`, `not_tracked`. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Posts a page when listing, up to 1000. Default: `100`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/posts?accounts=instagram%3A19237590&sort=recent&pageSize=5" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166. |

Example request:

```bash
curl "https://scansocial.com/api/v1/posts/instagram:3977858905957226656_1471684166" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Readings a page, up to 1000. Default: `200`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/posts/instagram:3977858905957226656_1471684166/history" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `posts` | query | string | No | Comma-separated post ids, as instagram:3977858905957226656_1471684166, up to 50, mixed platforms allowed. A platform id works when platform is sent. |
| `accounts` | query | string | No | 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` | query | enum | No | The platform of any platform ids. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `sort` | query | enum | No | Values: `recent`, `likes`. Default: `recent`. |
| `since` | query | string | No | Only comments written from then: YYYY-MM-DD or an ISO time. |
| `until` | query | string | No | Only comments written up to then: YYYY-MM-DD (that whole day) or an ISO time. |
| `q` | query | string | No | Words the text must all have, up to 8. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Comments a page, up to 1000. Default: `100`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/comments?pageSize=5" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free. Free for posts and accounts you track.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `id` | path | string | Yes | The post's id, the platform and its own id together, as instagram:3977858905957226656_1471684166. |
| `sort` | query | enum | No | Values: `recent`, `likes`. Default: `recent`. |
| `since` | query | string | No | Only comments written from then: YYYY-MM-DD or an ISO time. |
| `until` | query | string | No | Only comments written up to then: YYYY-MM-DD (that whole day) or an ISO time. |
| `q` | query | string | No | Words the text must all have, up to 8. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Comments a page, up to 1000. Default: `100`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/posts/instagram:3977858905957226656_1471684166/comments?pageSize=5" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

## Search

Search across the whole index: find posts, tags and accounts, and chart a topic over time. Comes with Enterprise; other plans get 403 plan_required.

### GET /v1/search/posts

**Search posts.** Posts on a topic from our public post data (Instagram, TikTok, YouTube, X). In smart mode, the default, a search for running shoes finds the posts about them, not only the ones that say it. keyword mode matches the words in captions and handles. For exact sets, leave out q and terms and choose posts with tags, excludeTags, accounts and excludeAccounts: these are plain rules with no AI, so a post is in the results only if it passes them. Narrow by platform, performance, creator size, creator category and the creator's audience. With no text it returns the top posts for the filters. Every post carries its platform and platformPostId, its platformAccountId and its tags. mediaUrls lists each image or video on the post, and is empty when we hold none, as with YouTube, which has only thumbnailUrl. A post has views, or estimatedViews instead where the platform hides the count and we work it out from likes. tags is null for a post we have not tagged. pagination.total is the topic's full size, the same posts /v1/search/timeline charts, so pageSize=1 sizes a topic.

**Runs on:** Comes with Enterprise.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | No | The topic to search for. |
| `terms` | query | string | No | Comma-separated keywords, up to 8. Use instead of q for several terms. |
| `match` | query | enum | No | Whether any or all terms must match. Values: `any`, `all`. Default: `any`. |
| `exact` | query | bool | No | Match terms as whole words only. |
| `mode` | query | enum | No | smart finds posts about the topic: the caption says it, or the post is tagged with it, even when the words never appear. keyword only finds posts with the exact words in the caption or handle. Values: `smart`, `keyword`. Default: `smart`. |
| `tags` | query | string | No | Comma-separated tags, up to 120. Posts must carry them, by the exact tag. Find tags with /v1/search/tags. |
| `tagMatch` | query | enum | No | Whether posts need any or all of tags. Values: `any`, `all`. Default: `any`. |
| `excludeTags` | query | string | No | Comma-separated tags, up to 120. Posts carrying any of them are left out. |
| `accounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Only these accounts' posts, collaborations included. An account we don't hold is a 404. |
| `excludeAccounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Their posts are left out, collaborations included. |
| `accountPlatform` | query | enum | No | The platform of any platform ids in accounts and excludeAccounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `combine` | query | enum | No | With both tags and accounts: and needs a post to pass both, or takes posts passing either, such as a topic's tagged posts plus a brand's own. Exclusions always apply, and an audience filter always means and. Values: `and`, `or`. Default: `and`. |
| `platforms` | query | csv | No | Comma-separated: instagram, tiktok, youtube, x. Values: `instagram`, `tiktok`, `youtube`, `x`. |
| `minViews` | query | int | No | On search this can only raise the bar above 1,000. |
| `maxViews` | query | int | No |  |
| `minFollowers` | query | int | No |  |
| `maxFollowers` | query | int | No |  |
| `categories` | query | string | No | Comma-separated creator categories. The values are under Filter values in the docs. |
| `accountTypes` | query | csv | No | Comma-separated: brand, influencer, institution. Values: `brand`, `influencer`, `institution`. |
| `countries` | query | string | No | Comma-separated ISO-2 codes of the audience. Only finds accounts this key tracks. |
| `countryThreshold` | query | number | No |  |
| `ageBands` | query | string | No | Comma-separated: 13-17, 18-24, 25-34, 35-44, 45-64, 65-. Only finds accounts this key tracks. |
| `ageThreshold` | query | number | No |  |
| `gender` | query | enum | No | The audience's gender. Only finds accounts this key tracks. Values: `female`, `male`. |
| `genderThreshold` | query | number | No |  |
| `postedWithinDays` | query | int | No | Days back, up to 365. Defaults to 365. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |
| `sort` | query | enum | No | relevance (the default with text in smart mode) ranks by how strongly a post is about the search; outliers ranks posts against their account's own average; surging ranks by recent growth. Without text the default is views. Values: `relevance`, `views`, `recent`, `likes`, `comments`, `outliers`, `surging`. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Items a page, up to 50. Default: `25`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/search/posts?q=matcha&platforms=tiktok%2Cinstagram&sort=views&pageSize=5" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

### GET /v1/search/accounts

**Search accounts by name.** Find creators and brands by name, or browse the biggest ones, filtered by size, growth, category, account type and audience make-up (country share, age bands, gender). This is the creator-discovery search an influencer platform or agency builds its shortlist on. Every account carries its platform and platformAccountId, which the lookup, posts and stats endpoints take. 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.

**Runs on:** Comes with Enterprise.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | No | Matched against handles and display names. |
| `terms` | query | string | No | Comma-separated keywords, up to 8. |
| `match` | query | enum | No | Whether any or all terms must match. Values: `any`, `all`. Default: `any`. |
| `fromDate` | query | string | No | The first day the numbers cover, YYYY-MM-DD, UTC. Inclusive. posts, views, likes, and comments, the view filters and the views sort all use these days, and only accounts that posted in them are found. With neither date, the last 90 days. |
| `toDate` | query | string | No | The last day the numbers cover, YYYY-MM-DD, UTC. Inclusive. |
| `platforms` | query | csv | No | Comma-separated: instagram, tiktok, youtube, x. Values: `instagram`, `tiktok`, `youtube`, `x`. |
| `minFollowers` | query | int | No |  |
| `maxFollowers` | query | int | No |  |
| `minViews` | query | int | No | Views across the account's posts in the period. |
| `maxViews` | query | int | No |  |
| `minGrowth` | query | number | No | Trailing 30-day likes against the account's normal month, percent. |
| `maxGrowth` | query | number | No |  |
| `categories` | query | string | No | Comma-separated creator categories. The values are under Filter values in the docs. |
| `accountTypes` | query | csv | No | Comma-separated: brand, influencer, institution. Values: `brand`, `influencer`, `institution`. |
| `countries` | query | string | No | Comma-separated ISO-2 codes of the audience. Only finds accounts this key tracks. |
| `countryThreshold` | query | number | No |  |
| `ageBands` | query | string | No | Comma-separated: 13-17, 18-24, 25-34, 35-44, 45-64, 65-. Only finds accounts this key tracks. |
| `ageThreshold` | query | number | No |  |
| `gender` | query | enum | No | The audience's gender. Only finds accounts this key tracks. Values: `female`, `male`. |
| `genderThreshold` | query | number | No |  |
| `postedWithinDays` | query | int | No | Only accounts that posted in the last N days. |
| `sort` | query | enum | No | country, female and male only find accounts this key tracks. Values: `followers`, `views`, `growth`, `country`, `female`, `male`. Default: `followers`. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Items a page, up to 50. Default: `25`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/search/accounts?q=nhl" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

### GET /v1/search/accounts/by-content

**Accounts posting about a topic.** The accounts behind a topic, from the same posts the same search finds on /v1/search/posts, with the same filters. Each comes with its profile, plus topicPosts, topicViews, topicLikes and topicComments: how many of those posts are its and what they earned. Shows who owns a conversation: the creators to partner with, or the competitors taking the attention. Sort by views for who carries the most attention, or by posts for who talks about it most. 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.

**Runs on:** Comes with Enterprise.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | No | The topic to search for. |
| `terms` | query | string | No | Comma-separated keywords, up to 8. Use instead of q for several terms. |
| `match` | query | enum | No | Whether any or all terms must match. Values: `any`, `all`. Default: `any`. |
| `exact` | query | bool | No | Match terms as whole words only. |
| `mode` | query | enum | No | smart finds posts about the topic: the caption says it, or the post is tagged with it, even when the words never appear. keyword only finds posts with the exact words in the caption or handle. Values: `smart`, `keyword`. Default: `smart`. |
| `tags` | query | string | No | Comma-separated tags, up to 120. Posts must carry them, by the exact tag. Find tags with /v1/search/tags. |
| `tagMatch` | query | enum | No | Whether posts need any or all of tags. Values: `any`, `all`. Default: `any`. |
| `excludeTags` | query | string | No | Comma-separated tags, up to 120. Posts carrying any of them are left out. |
| `accounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Only these accounts' posts, collaborations included. An account we don't hold is a 404. |
| `excludeAccounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Their posts are left out, collaborations included. |
| `accountPlatform` | query | enum | No | The platform of any platform ids in accounts and excludeAccounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `combine` | query | enum | No | With both tags and accounts: and needs a post to pass both, or takes posts passing either, such as a topic's tagged posts plus a brand's own. Exclusions always apply, and an audience filter always means and. Values: `and`, `or`. Default: `and`. |
| `platforms` | query | csv | No | Comma-separated: instagram, tiktok, youtube, x. Values: `instagram`, `tiktok`, `youtube`, `x`. |
| `minViews` | query | int | No | On search this can only raise the bar above 1,000. |
| `maxViews` | query | int | No |  |
| `minFollowers` | query | int | No |  |
| `maxFollowers` | query | int | No |  |
| `categories` | query | string | No | Comma-separated creator categories. The values are under Filter values in the docs. |
| `accountTypes` | query | csv | No | Comma-separated: brand, influencer, institution. Values: `brand`, `influencer`, `institution`. |
| `countries` | query | string | No | Comma-separated ISO-2 codes of the audience. Only finds accounts this key tracks. |
| `countryThreshold` | query | number | No |  |
| `ageBands` | query | string | No | Comma-separated: 13-17, 18-24, 25-34, 35-44, 45-64, 65-. Only finds accounts this key tracks. |
| `ageThreshold` | query | number | No |  |
| `gender` | query | enum | No | The audience's gender. Only finds accounts this key tracks. Values: `female`, `male`. |
| `genderThreshold` | query | number | No |  |
| `postedWithinDays` | query | int | No | Days back, up to 365. Defaults to 365. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |
| `minPosts` | query | int | No | Posts on the topic an account needs. |
| `sort` | query | enum | No | Values: `posts`, `views`, `likes`, `comments`, `followers`. Default: `posts`. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Items a page, up to 50. Default: `25`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/search/accounts/by-content?q=matcha&sort=views" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

### GET /v1/search/timeline

**A topic or account over time.** The numbers to chart a search, an account or any set of filters: per hour, day, week or month, the posts made, the accounts posting and their views, likes, comments, shares, saves and reposts, plus totals across the whole window for sizing a topic or comparing share of voice. Each point has date, the start of its bucket. It counts every post on the topic, in whichever mode you choose, so totals match total on /v1/search/posts, with whole days counted in a window. Buckets with no posts come back as zeros, across the whole window when one is set. The metrics sit on the bucket a post went up in, at their current totals. groupBy splits the same posts by platform, account or tag: each group has its own totals and series, so its totals give the distribution and its series the line over time, and the response has the overall totals but no overall series. Platforms all come back. Accounts and tags return the top groupLimit by groupSort. Accounts beyond the limit are summed into an other group, so the groups add up to the totals, with a collaboration counted under the post's main account. If you send accounts, you get those accounts instead, each counting its collaborations. A post has several tags, so tag groups overlap and don't add up to the totals. If you send tags, you get those tags instead of the most used. include adds extras: attention, a 0 to 100 score per bucket, which needs the overall series and so can't be used with groupBy; themes, the groups of posts inside the topic and whether each is growing.

**Runs on:** Comes with Enterprise.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | No | The topic to search for. |
| `terms` | query | string | No | Comma-separated keywords, up to 8. Use instead of q for several terms. |
| `match` | query | enum | No | Whether any or all terms must match. Values: `any`, `all`. Default: `any`. |
| `exact` | query | bool | No | Match terms as whole words only. |
| `mode` | query | enum | No | smart finds posts about the topic: the caption says it, or the post is tagged with it, even when the words never appear. keyword only finds posts with the exact words in the caption or handle. Values: `smart`, `keyword`. Default: `smart`. |
| `tags` | query | string | No | Comma-separated tags, up to 120. Posts must carry them, by the exact tag. Find tags with /v1/search/tags. |
| `tagMatch` | query | enum | No | Whether posts need any or all of tags. Values: `any`, `all`. Default: `any`. |
| `excludeTags` | query | string | No | Comma-separated tags, up to 120. Posts carrying any of them are left out. |
| `accounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Only these accounts' posts, collaborations included. An account we don't hold is a 404. |
| `excludeAccounts` | query | string | No | Comma-separated account ids, as instagram:19237590, up to 50, mixed platforms allowed. A platform id works when accountPlatform is sent. Their posts are left out, collaborations included. |
| `accountPlatform` | query | enum | No | The platform of any platform ids in accounts and excludeAccounts. Values: `instagram`, `tiktok`, `youtube`, `x`, `facebook`, `linkedin`, `snapchat`. |
| `combine` | query | enum | No | With both tags and accounts: and needs a post to pass both, or takes posts passing either, such as a topic's tagged posts plus a brand's own. Exclusions always apply, and an audience filter always means and. Values: `and`, `or`. Default: `and`. |
| `platforms` | query | csv | No | Comma-separated: instagram, tiktok, youtube, x. Values: `instagram`, `tiktok`, `youtube`, `x`. |
| `minViews` | query | int | No | On search this can only raise the bar above 1,000. |
| `maxViews` | query | int | No |  |
| `minFollowers` | query | int | No |  |
| `maxFollowers` | query | int | No |  |
| `categories` | query | string | No | Comma-separated creator categories. The values are under Filter values in the docs. |
| `accountTypes` | query | csv | No | Comma-separated: brand, influencer, institution. Values: `brand`, `influencer`, `institution`. |
| `countries` | query | string | No | Comma-separated ISO-2 codes of the audience. Only finds accounts this key tracks. |
| `countryThreshold` | query | number | No |  |
| `ageBands` | query | string | No | Comma-separated: 13-17, 18-24, 25-34, 35-44, 45-64, 65-. Only finds accounts this key tracks. |
| `ageThreshold` | query | number | No |  |
| `gender` | query | enum | No | The audience's gender. Only finds accounts this key tracks. Values: `female`, `male`. |
| `genderThreshold` | query | number | No |  |
| `postedWithinDays` | query | int | No | Days back, up to 365. Defaults to 365. |
| `fromDate` | query | string | No | The first day, YYYY-MM-DD, UTC. Inclusive. |
| `toDate` | query | string | No | The last day, YYYY-MM-DD, UTC. Inclusive. |
| `bucket` | query | enum | No | Values: `hour`, `day`, `week`, `month`. Default: `day`. |
| `groupBy` | query | enum | No | Split the posts into groups, each with its own totals and series. Values: `platform`, `account`, `tag`. |
| `groupLimit` | query | int | No | How many account or tag groups to return. Defaults to 10, or every tag you send. |
| `groupSort` | query | enum | No | Which metric picks and orders the top groups. Values: `posts`, `views`, `likes`, `comments`, `shares`, `saves`, `reposts`. Default: `posts`. |
| `include` | query | csv | No | Comma-separated extras: attention, themes. Values: `attention`, `themes`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/search/timeline?q=matcha&postedWithinDays=90&bucket=week&groupBy=platform" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

### GET /v1/search/tags

**Find tags.** The tags posts carry that contain these words, most used first, with how many posts and accounts have each, to send as tags or excludeTags on the other post endpoints. The counts cover the same window, 90 days unless you set one. Posts carry tags for up to a year, and a new post can't match a tag until it has been tagged.

**Runs on:** Comes with Enterprise.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `q` | query | string | Yes | A word or the start of one, matched at the start of any word in a tag. |
| `platforms` | query | csv | No | Comma-separated: instagram, tiktok, youtube, x. Values: `instagram`, `tiktok`, `youtube`, `x`. |
| `postedWithinDays` | query | int | No | Days back, up to 365. Defaults to 365. |
| `page` | query | int | No | Which page, from 1. Default: `1`. |
| `pageSize` | query | int | No | Items a page, up to 50. Default: `25`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/search/tags?q=matcha" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free.

No parameters.

Example request:

```bash
curl "https://scansocial.com/api/v1/plan" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```

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

**Runs on:** Free.

| Parameter | In | Type | Required | Details |
| --- | --- | --- | --- | --- |
| `days` | query | int | No | How many days back, today included. Up to 90. Default: `30`. |

Example request:

```bash
curl "https://scansocial.com/api/v1/usage" \
  -H "x-api-key: $SCANSOCIAL_KEY"
```
