> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://api.docs.siftsy.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://api.docs.siftsy.com/_mcp/server.

# Siftsy Analyst API

> Put Siftsy's comment intelligence in your analyst workflow: add the posts you need to read, run analyses, and export key insights into your reporting, warehouse, or AI chat.

Siftsy reads the comments on your posts and scores how people reacted: how they feel, whether they stayed on topic, whether they agree with each other, and how the message and subject landed. You already see that in the dashboard for a post, a campaign, or any set of posts you pick. The **Siftsy Analyst API** brings that same picture into the workflows analysts already run, in the tools they already use.

It is built for the analysts on social insights, PR and comms, and social, community, and influencer teams, in two directions:

* **Add the posts you need to read.** Campaign and creator posts, a competitor's posts, owned posts, or a public account's recent posts go into Siftsy programmatically, spending the same credits and running the same processing as Add New in the app. → [Adding content](/guides/core-concepts/adding-content)
* **Export key analyses and insights.** Scores, mix bars, per-post analyses, selection analyses, and the reports teammates saved in the app come out as stable, paginated JSON that lands cleanly in Snowflake, BigQuery, Databricks, Redshift, or a BI tool such as Power BI, Tableau, or Looker. → [BI sync](/guides/core-concepts/bi-sync)

Every number the API returns is what Siftsy has already computed: it does not rescore posts, edit collections, or invent new scores, so an API result matches what a teammate sees in the dashboard. Comment routes return a **sample of evidence** behind an analysis, not a full thread — Siftsy is an analysis platform, not a comment exporter.

The same key also works as an **MCP (beta)** from Cursor, Claude Code, or a stdio bridge: ask how a campaign landed, paste a post link to analyze it (and add it if it is new), and get back the numbers and quotes for a deck. The REST API stays the stable contract for warehouses. → [MCP](/guides/get-started/mcp)

## What teams use it for

The API covers the same jobs teams use Siftsy for in the app:

| Use case                                              | What you pull                                                                                               |
| ----------------------------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| Measure how a campaign actually landed                | A campaign collection's scores and mix, per creator and per post, and a readout you can drop into reporting |
| Read the room during a crisis or viral moment         | Sentiment and consensus on the posts carrying the conversation, week by week, plus the quotes that show it  |
| Track how a brand or product is perceived             | Scores over time for a brand's or product's posts, by content tag or platform                               |
| See what people say on a competitor's posts           | A comparison of your posts and theirs over the same window                                                  |
| Turn thousands of comments into themes                | A written answer that cites real comments, plus the share of comments behind each theme                     |
| Pull the exact quotes that prove your point           | A sample of notable comments behind an analysis, with author, likes, and post link                          |
| Explain the why behind engagement numbers             | Engagement next to sentiment and consensus, post by post                                                    |
| Surface recurring questions, complaints, and requests | A filtered or searched analysis for asks, complaints, or "where can I buy" comments                         |
| Validate a hunch before you spend budget              | The claim tested against the comments, with the share that supports it                                      |

Create a key under **Team Settings → API**, then start here:

#### [Quickstart](/guides/get-started/quickstart)

Create a key and make your first request.

#### [MCP (beta)](/guides/get-started/mcp)

Same key, from Cursor, Claude, or ChatGPT. In beta.

#### [API reference](/api-reference/overview/api-reference)

Every endpoint, parameter, and example.

## How it fits together

The Analyst API follows the same three steps you use in the product:

```
 1. Select Content     ──▶  2. Comment Analysis  ──▶  3. View Individual Comments
```

**Select Content.** Select posts the way you would in the dashboard: select posts by collection, content tag, filter by creator, platform, link, date, score, or sentiment, or pass specific post ids or links. That description is resolved when you call, and it caps at 1,000 posts. → [Content selection](/guides/core-concepts/content-selection)

**Comment Analysis** is what the audience said. Each analysis has two sides: what was posted (the content, topics, and messages it was scored against) and how commenters responded (sentiment, relevance, consensus, content, and topic scores, plus the mix bars). You can narrow to a slice — a mix-bar bucket, keywords, usernames, and so on — or search in plain language. The numbers then describe only the matching comments, and `scope` tells you how big that slice is. → [Analyses](/guides/core-concepts/analyses)

**Get comments.** The analysis does not include comment bodies. Follow `comments.path` to get a sample of the comments behind the numbers. → [Retrieving comments](/guides/core-concepts/retrieving-comments)

Two things stay true throughout:

* **The numbers match the dashboard.** Scores, mix bars, filters, and search use the same paths the product uses, so an API result matches what a teammate sees when they click the same thing.
* **Simple reads come back immediately. Heavier ones run as a job.** A snapshot of stored scores returns in the same request. AI search, or a very large selection, is queued. Both use the same `Analysis` object with a `status`, so your client can always: create, poll if you get a `202`, then sample the comments behind it.

## Adding content

The pipeline above reads posts that are already in your workspace. Getting them there is a separate, **write** path, and it is the only one the API has — for adding a new campaign's creator posts, a competitor's account, or the posts behind a viral moment without pasting links into the app:

```
 POST /content/posts/add        ──▶  Content job  ──▶  posts process  ──▶  readable in GET /posts
 POST /content/accounts/add          (poll it)        (same as Add New)     (addedVia: api)
```

Give a key the opt-in `posts:write` / `accounts:write` scopes and it can add posts by URL, or pull a public account's recent posts filtered by date, engagement, and caption. It spends the same credits and runs the same processing as Add New in the app, so a teammate would get the identical result by pasting the links. You get back a content job that tells you what was accepted, skipped, or rejected, and how the accepted posts are progressing; once they are `complete` they are ordinary posts for the pipeline above. → [Adding content](/guides/core-concepts/adding-content)

```bash
POST /analyst/v1/content/posts/add
{ "links": ["https://www.tiktok.com/@dove/video/7412345678901234567"], "tags": ["holiday"] }
#   → 202 Location: /analyst/v1/content/jobs/cj_…   then GET until status is "completed"
```

Nothing in the export pipeline depends on it: if teammates add content in the app, the API is read-only and the write scopes stay off.

## Exporting to your warehouse

Everything the read routes return is designed to be loaded, not screen-scraped: cursor pagination, `updated_since` for incrementals, stable ids, one JSON shape per resource, and rate limits sized for a scheduled refresh rather than a realtime feed. A typical load pulls collections → posts → per-post metrics and analysis → saved reports, then samples comments only where a dashboard needs evidence. → [BI sync](/guides/core-concepts/bi-sync), [Rate limits](/guides/core-concepts/rate-limits)

## Guides

#### [Content selection](/guides/core-concepts/content-selection)

Choose posts with collections, tags, filters, or ids. The same selection lists posts and drives an analysis.

#### [Analyses](/guides/core-concepts/analyses)

Creator side vs. audience side, the four kinds of analysis, narrowing vs. searching, and when a call becomes a job.

#### [Post analysis](/guides/core-concepts/post-analysis)

The saved per-post view, field by field, with a full example payload.

#### [Scores and mix](/guides/core-concepts/scores)

Sentiment, content, topic, relevance, and consensus on a 1–10 scale, and how the five mix buckets map to the dashboard. Consensus is about other commenters, not the post.

#### [Filtering posts](/guides/core-concepts/filtering-posts)

Every post filter, how matching works, and how filters work with paging.

#### [Exploring and exporting](/guides/core-concepts/exploring)

Match your own links, scan for what stands out, break it down, compare, get cited answers, and export joinable tables.

#### [Retrieving comments](/guides/core-concepts/retrieving-comments)

Sample the comments behind an analysis, then narrow that sample by mix-bar bucket. Not a full-thread export.

#### [Collections and BI sync](/guides/core-concepts/bi-sync)

Campaigns and groups as they appear in Siftsy, plus a sensible load order for a warehouse.

#### [Auth, limits, paging](/guides/core-concepts/authentication)

Team API keys and scopes, rate limits, and cursor pagination.

#### [Adding content](/guides/core-concepts/adding-content)

The write path: add posts by URL or a public account's recent posts, with the same credits and processing as Add New. How the ingest runs and what a post goes through.

## What to call when

| You want to…                                                              | Call                                                                               |
| ------------------------------------------------------------------------- | ---------------------------------------------------------------------------------- |
| See who the key belongs to, and how the team scores                       | `GET /me`, `GET /team`                                                             |
| List collections, or see what is in one                                   | `GET /collections`, `GET /collections/{id}`, `GET /collections/{id}/posts`         |
| Find posts by filters or tags                                             | `GET /posts`, `GET /posts/{id}`                                                    |
| Get scores for one post                                                   | `GET /posts/{id}/metrics`                                                          |
| Get the full analysis for one post                                        | `GET /posts/{id}/analysis`                                                         |
| Analyze a set of posts, with filters or search                            | `POST /analyses` → `GET /analyses/{id}`                                            |
| List analyses you have already run, including saved reports               | `GET /analyses`                                                                    |
| Sample comments behind a post analysis                                    | `GET /posts/{id}/analysis/comments?source=notables`                                |
| Sample comments behind a selection analysis                               | `GET /analyses/{id}/comments?source=notables`                                      |
| Pull analyses teammates saved or shared in the app                        | `GET /snapshots`, `GET /insights`                                                  |
| Match links from your own data to Siftsy posts                            | `POST /posts/match`                                                                |
| Find the posts that stand out in a selection                              | `POST /posts/scan`                                                                 |
| Roll a selection up by account, platform, tag, collection, week, or month | `POST /breakdowns`                                                                 |
| Compare 2–4 selections, or get a cited written answer                     | `POST /analyses` with `compare` or `answer`                                        |
| Export an analysis as a flat CSV or JSON table                            | `GET /analyses/{id}/export`                                                        |
| Add posts by URL, or a public account's recent posts (write scopes)       | `POST /content/posts/add`, `POST /content/accounts/add` → `GET /content/jobs/{id}` |

Lists come back in pages of up to 100. If there are more, send the same filters with the `cursor`. See [Pagination](/guides/core-concepts/pagination).

## A full pass

```bash
# 1. Pick the posts — or skip this and go straight to the analysis
GET /analyst/v1/posts?account=@dove&platform=tiktok&tag=holiday

# 2. Analyze them. Here: on-topic comments that look like requests.
POST /analyst/v1/analyses
{ "selection": { "posts": { "account": "@dove", "platform": "tiktok", "tag": "holiday" } },
  "filters":   { "relevance": ["on_topic"], "keywords": ["please", "available", "uk"] } }
#   → 201 { status: "ready", scope: { totalComments: 128, matchedComments: 23, shareOfComments: 0.18 }, … }

# 2b. Or ask a question in plain language — that needs a model, so it queues
POST /analyst/v1/analyses
{ "selection": { "collectionId": "col_dove_influencers" },
  "search":    { "query": "asking for PR packages or to become an ambassador" } }
#   → 202 Location: /analyst/v1/analyses/an_…   then GET until status is "ready"

# 3. Sample the comments behind those numbers (not the full thread)
GET /analyst/v1/analyses/an_…/comments?source=notables
```

[Analyses](/guides/core-concepts/analyses#worked-example-dove-and-dove-influencers) walks this same sequence on a Dove brand + influencer campaign, with real responses.

## Base URL

```
https://api.siftsy.app/analyst/v1
```

Send your key as `Authorization: Bearer YOUR_API_KEY` or `X-Api-Key`. See [Authentication](/guides/core-concepts/authentication) and [Rate limits](/guides/core-concepts/rate-limits).