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

# Retrieving comments

> Sample the comments behind an analysis, then narrow that sample by mix-bar bucket.

`GET /posts/{postId}/analysis/comments` and `GET /analyses/{analysisId}/comments` return a **sample of comments behind the analysis** — the evidence for the scores and mix bars, not the whole thread.

> **Warning**
>
> Siftsy is an **analysis platform**, not a comment exporter. These routes are not a way to dump full comment sections into a warehouse. Ask for a sample (`source=notables`, `content`, or `all`), optionally narrowed to a mix-bar bucket. Prefer the analysis numbers themselves when you need totals or mix.

The sample uses the same five-bucket keys as the analysis mix bars and `GET /posts/{postId}/metrics`. Mix-bar filters below narrow that sample.

Values within one parameter combine with **OR**. Different parameters combine with **AND**. Unscored comments are excluded when you filter that dimension. Active filters are echoed in `meta.filters`.

| Filter      | What it does                                          | Example                          |
| ----------- | ----------------------------------------------------- | -------------------------------- |
| `sentiment` | Overall sentiment bucket                              | `sentiment=positive`             |
| `content`   | Content sentiment (alignment with the post / creator) | `content=positive,lean_positive` |
| `topic`     | Topic sentiment (reception of the subject)            | `topic=negative`                 |
| `relevance` | How on-topic the comment is                           | `relevance=on_topic`             |
| `consensus` | How the commenter is reacting to **other commenters** | `consensus=fighting`             |

Canonical keys on every dimension: `positive`, `lean_positive`, `neutral`, `lean_negative`, `negative`.

Relevance and consensus also accept the dashboard labels:

| Key             | Sentiment     | Relevance   | Consensus    |
| --------------- | ------------- | ----------- | ------------ |
| `positive`      | Positive      | `on_topic`  | `agreeing`   |
| `lean_positive` | Lean positive | `relevant`  | `discussing` |
| `neutral`       | Neutral       | —           | —            |
| `lean_negative` | Lean negative | `general`   | `debating`   |
| `negative`      | Negative      | `off_topic` | `fighting`   |

`neutral` is typically unused for relevance and consensus. Score version 3 overall sentiment has a true unused middle band (4.5–5.5); v1/v2 overall sentiment does not. Content and topic always use the five-bucket split. See [Scores](/guides/core-concepts/scores) for numeric cutoffs.

> **Warning**
>
> **Consensus is not agreement with the post.** `consensus=fighting` is commenters arguing with each other. A thread can be uniformly negative toward the post and still have high consensus.

## Examples

Comments in the positive overall-sentiment bar:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts/YOUR_POST_ID/analysis/comments?sentiment=positive"
```

On-topic comments that are fighting with other commenters:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts/YOUR_POST_ID/analysis/comments?relevance=on_topic&consensus=fighting"
```

Content-positive and topic-negative (split reaction: aligned with the creator, hostile to the subject):

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts/YOUR_POST_ID/analysis/comments?content=positive&topic=negative"
```

Each comment in the response includes `scores` (1–10) and `buckets` (the mix-bar key), so you can confirm the filter matched the values you got back. Invalid bucket names return `400`.

Pass `source=` to choose the sample:

| `source`   | What you get                                                        |
| ---------- | ------------------------------------------------------------------- |
| `notables` | Highest-engagement, most relevant comments (the usual evidence set) |
| `content`  | Comments grouped onto the creator’s topics and messages             |
| `all`      | The union of those two                                              |

Sampled rows include `sampleReasons`. `meta.groups` lists creator topics and messages with `commentCount` and `sampleCommentIds`. See [Post analysis](/guides/core-concepts/post-analysis). The same filters work on `GET /analyses/{analysisId}/comments`.

## Filtering at analysis time

The query-string filters above narrow the **sample** after the analysis already exists. To make the **analysis itself** describe a narrowed set — so scores, mix bars, and share-of-comments all reflect it — pass `filters` to [`POST /analyses`](/guides/core-concepts/analyses). That accepts the same bucket names plus the rest of the dashboard controls: keywords, usernames, creator comments, replies, questions, mentions, emoji-only comments, a likes floor, and a date range. `GET /analyses/{analysisId}/comments` then applies the analysis's filters first and samples from that matched set.