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

# Exploring and exporting

> Comb through a workspace, find what stands out, back it with comments, and export tables that join with your own data.

The routes in [Analyses](/guides/core-concepts/analyses) answer a question you already have. The routes on this page help you find the question: look across a lot of posts, see what stands out, dig into it, and take the result somewhere else. Every step returns stable ids and the same join keys, so the output merges cleanly with the data you already report from: a campaign tracker, a creator list, or post performance from your social or listening tools.

Typical passes:

* **Campaign readout.** Scan a campaign collection, see which creators and posts landed or missed, and explain the engagement numbers with the comments.
* **Crisis or viral moment.** Scan the posts carrying the conversation, find where commenters are fighting each other or going off topic, and pull the quotes for comms.
* **Competitor read.** Compare your posts with a competitor's over the same window, side by side.
* **Creative and product signals.** Break down by content tag or week to see which themes, questions, complaints, and requests keep coming back.

```
Match ──▶ Scan ──▶ Break down ──▶ Analyze / compare / answer ──▶ Export
```

Nothing on this page rescores posts or changes the workspace. Scans and breakdowns read stored post scores, so they are fast and never load comments.

## Join keys

Post rows from `POST /posts/match`, `POST /posts/scan`, and `GET /analyses/{id}/export?table=posts` all carry the same keys:

| Key                     | What it is                                                                              |
| ----------------------- | --------------------------------------------------------------------------------------- |
| `postId`                | Siftsy post id. Feeds `selection.postIds`                                               |
| `link`                  | The post URL as stored                                                                  |
| `platform`              | `tiktok`, `instagram`, `youtube`, …                                                     |
| `account`               | Creator handle, lowercase, without `@` — the same key as `by: account` breakdown groups |
| `postedAt`              | ISO-8601 publish time                                                                   |
| `collectionIds`, `tags` | Campaigns / groups and content tags the post is in                                      |

Scores are 1–10 and shares (`shareOfComments`, `share.ofPosts`, …) are 0–1 fractions everywhere, so math across tables stays consistent. Mix bars and `engagementRate` are percentages (0–100). Week and month keys are the period's first day (`2026-09-07`, `2026-09-01`) in breakdowns and timelines alike.

## 1. Match your own links

If your data already names posts — the creator posts in a campaign tracker, a list of posts that went viral, or the top posts from your social reporting — resolve those links first:

```bash
curl -sS -X POST -H "Authorization: Bearer $SIFTSY_API_KEY" -H "Content-Type: application/json" \
  https://api.siftsy.app/analyst/v1/posts/match \
  -d '{ "links": [
        "https://www.tiktok.com/@dove/video/7583010641535831351?is_from_webapp=1",
        "https://www.tiktok.com/@dove/video/7599999999999999999",
        "https://example.com/not-a-post"
      ] }'
```

Each link comes back once, in order, with a `status` — `matched`, `processing`, `failed`, `not_in_workspace`, `invalid_url`, or `unsupported_platform` — and `meta.matchedPostIds` ready to use as a selection. Query strings, `www.`, `http` vs `https`, and trailing slashes do not break a match. Short links (`vm.tiktok.com`, `youtu.be`) only match if that short link itself was added, so send full post URLs when you have them. Links that are `not_in_workspace` can be added with [`POST /content/posts/add`](/guides/core-concepts/adding-content) if the key has the write scopes.

## 2. Scan for what stands out

`POST /posts/scan` returns one row per post in a selection, compared with the selection's own baseline — the comment-weighted rollup of the same posts, the same math as the dashboard's combined-by-account rows.

```bash
curl -sS -X POST -H "Authorization: Bearer $SIFTSY_API_KEY" -H "Content-Type: application/json" \
  https://api.siftsy.app/analyst/v1/posts/scan \
  -d '{ "selection": { "collectionId": "col_dove_influencers" },
        "sort": { "by": "sentiment", "order": "asc" }, "limit": 10 }'
```

Posts with at least 10 analyzed comments get `flags`:

| Flag                                | Rule                                                                                                          |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `negative_sentiment`                | Sentiment under 4.5                                                                                           |
| `below_baseline` / `above_baseline` | Sentiment 1.5+ below / above the selection baseline                                                           |
| `commenters_arguing`                | 25%+ of comments in the debating or fighting consensus bands                                                  |
| `off_topic`                         | Relevance under 4.5 — the post is being used as a venue for something else                                    |
| `content_topic_gap`                 | Content and topic scores 2+ points apart — the audience likes the creator but not the subject, or the reverse |
| `high_engagement_negative`          | Engagement rate in the selection's top quarter while sentiment is negative                                    |

> **Warning**
>
> **`commenters_arguing` is about commenters, not the post.** Consensus measures how commenters react to each other. A thread can be uniformly negative toward the post and still have high consensus.

Send `flags: ["off_topic", "commenters_arguing"]` to keep only flagged posts. Flags say where to look; an analysis on those posts says why. `format: "csv"` returns every row in one call.

## 3. Break it down

`POST /breakdowns` rolls a selection up by `account`, `platform`, `tag`, `contentType`, `collection`, `week`, or `month`:

```bash
curl -sS -X POST -H "Authorization: Bearer $SIFTSY_API_KEY" -H "Content-Type: application/json" \
  https://api.siftsy.app/analyst/v1/breakdowns \
  -d '{ "selection": { "collectionId": "col_dove_influencers" }, "by": "account" }'
```

Each group has its post and comment counts, its share of the selection, summed engagement with a pooled engagement rate, comment-weighted scores and mix bars, and `baselineDelta` against the whole selection (`meta.overall`). A post with several tags or collections counts in each of them. `by: collection` also needs `collections:read`.

## 4. Analyze, compare, answer

Once you know where to look, [`POST /analyses`](/guides/core-concepts/analyses) reads the comments themselves. Three options are built for this workflow:

* **`compare`** — 2–4 sides, each its own selection: brand vs competitor, this month vs last, campaign A vs B. Filters and search apply to every side, and `comparison.deltas` gives each side against side 1.
* **`answer`** — a written finding with every claim citing real comments. The citations resolve to author, likes, and post link, so a quote in your report traces back to the comment. Needs `comments:read`.
* **`include: ["timeline"]`** — Scores over Time by day, week, or month, by comment date or post date. `include: ["languages"]` and `filters.languages` cover multilingual audiences.

```bash
curl -sS -X POST -H "Authorization: Bearer $SIFTSY_API_KEY" -H "Content-Type: application/json" \
  https://api.siftsy.app/analyst/v1/analyses \
  -d '{ "compare": [
          { "label": "Dove", "selection": { "posts": { "account": "@dove", "posted_since": "2026-08-29" } } },
          { "label": "Olay", "selection": { "posts": { "account": "@olay", "posted_since": "2026-08-29" } } }
        ],
        "filters": { "creator": "exclude" },
        "include": ["timeline"], "timeline": { "granularity": "week" } }'
```

## 5. Export

Every ready analysis has `export.url`. Pick a `table` and a `format`:

| Table       | Rows                                                                            |
| ----------- | ------------------------------------------------------------------------------- |
| `posts`     | One per post: join keys, stored scores, and `matchedComments` for this analysis |
| `sides`     | One per comparison side, with deltas against side 1                             |
| `timeline`  | One per period (and per side)                                                   |
| `languages` | One per language (and per side)                                                 |
| `citations` | The comments behind `answer` (needs `comments:read`)                            |

```bash
curl -sS -H "Authorization: Bearer $SIFTSY_API_KEY" \
  "https://api.siftsy.app/analyst/v1/analyses/an_…/export?table=posts&format=csv" -o dove_posts.csv
```

CSV headers are dot paths (`scores.sentiment`, `mix.consensus.negativePercent`), and every table keeps the same columns from call to call — an unknown value is an empty cell, never a missing column. Text cells a spreadsheet would read as a formula (starting with `=`, `+`, `-`, `@`) are prefixed with `'`; breakdown labels such as `@dove` come out as `'@dove`, so join on `account` (no `@`) instead. JSON exports return the same flat rows with `meta.columns`; scans and breakdowns return nested JSON rows with `meta.csvColumns`, and take `format: "csv"` directly.

Exports count against the daily transfer budget like any response. They are post-, group-, and period-level numbers plus the comments an answer cites — not a comment export. For evidence, sample comments with [`GET /analyses/{id}/comments`](/guides/core-concepts/retrieving-comments).

## Rate classes

| Route                          | Class             | Budget per key         |
| ------------------------------ | ----------------- | ---------------------- |
| `POST /posts/match`            | `posts_match`     | 20 / minute, 500 / day |
| `POST /posts/scan`             | `posts_scan`      | 20 / minute, 500 / day |
| `POST /breakdowns`             | `breakdowns`      | 20 / minute, 500 / day |
| `GET /analyses/{id}/export`    | `analysis_export` | 30 / minute, 500 / day |
| `POST /analyses` with `answer` | `analysis_search` | 2 / minute, 10 / day   |

See [Rate limits](/guides/core-concepts/rate-limits).