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

# Filtering posts

> Find exactly the posts you want by link, account, platform, date, Siftsy score, or sentiment.

`GET /posts` and `GET /collections/{collectionId}/posts` accept the same set of filters. Add as many as you need — they combine with **AND**, so a post must match every filter to be returned. The same filters define a **content selection** for [`POST /analyses`](/guides/core-concepts/analyses) (`selection.posts`).

| Filter                                                    | What it does                                                                | Example                                           |
| --------------------------------------------------------- | --------------------------------------------------------------------------- | ------------------------------------------------- |
| `link`                                                    | Only the post at this URL                                                   | `link=https://www.instagram.com/reel/ABC123/`     |
| `account`                                                 | Only posts from this creator                                                | `account=@nike`                                   |
| `tag`                                                     | Only posts carrying this content tag                                        | `tag=launch`                                      |
| `platform`                                                | Only posts from these platforms                                             | `platform=instagram,tiktok`                       |
| `posted_since` / `posted_until`                           | Posts published in a date range                                             | `posted_since=2026-01-01&posted_until=2026-03-31` |
| `updated_since`                                           | Posts whose Siftsy data changed since a date                                | `updated_since=2026-03-01T00:00:00Z`              |
| `min_score` / `max_score`                                 | Siftsy score range (0–10)                                                   | `min_score=7`                                     |
| `min_positive_percent` / `max_positive_percent`           | Share of positive comments (0–100)                                          | `min_positive_percent=60`                         |
| `min_negative_percent` / `max_negative_percent`           | Share of negative comments (0–100)                                          | `max_negative_percent=10`                         |
| `min_neutral_percent` / `max_neutral_percent`             | Share of neutral comments                                                   | `max_neutral_percent=30`                          |
| `min_lean_positive_percent` / `max_lean_positive_percent` | Share of lean-positive comments                                             |                                                   |
| `min_lean_negative_percent` / `max_lean_negative_percent` | Share of lean-negative comments                                             |                                                   |
| `status`                                                  | Which processing states to include (default `complete`)                     | `status=all`                                      |
| `collectionId`                                            | Restrict to one collection (`GET /posts` only). `collection_id` is an alias | `collectionId=abc123`                             |

## Examples

Posts with a Siftsy score of 7 or higher:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?min_score=7"
```

Everything from one creator on TikTok this quarter:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?account=@nike&platform=tiktok&posted_since=2026-07-01&posted_until=2026-09-30"
```

Posts where at least 60% of comments are positive and no more than 10% are negative:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?min_positive_percent=60&max_negative_percent=10"
```

Look up a single post by its URL:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?link=https://www.instagram.com/reel/ABC123/"
```

Low-scoring posts inside one collection:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/collections/YOUR_COLLECTION_ID/posts?max_score=4"
```

Posts tagged `launch` or `preorder`:

```bash
curl -sS -H "Authorization: Bearer YOUR_API_KEY" \
  "https://api.siftsy.app/analyst/v1/posts?tag=launch,preorder"
```

The same selection as an analysis body:

```json
{ "selection": { "posts": { "tag": "launch,preorder" } } }
```

## How matching works

* **Links** are matched loosely: `http` vs `https`, `www.`, trailing slashes, upper/lower case, and anything after `?` or `#` are ignored. Tracking parameters like `?igsh=` or `?utm_source=` never break a match.
* **Accounts** match the creator's username or display name, case-insensitive. The leading `@` is optional.
* **Tags** are the content tags on the post in Siftsy, matched case-insensitively. The leading `#` is optional. Several tags match posts carrying **any** of them.
* **Lists**: `link`, `account`, `tag`, and `platform` accept several values — comma-separate them (`platform=instagram,tiktok`) or repeat the parameter.
* **Dates** are ISO 8601. A date without a time (`2026-01-01`) means midnight UTC.
* **Scores and percentages** compare against the values in the post payload (`scores.siftsyScore` and `sentimentMix.*`), so what you filter on is exactly what you get back. Posts that have not finished scoring are excluded from score and sentiment filters.

> **Tip**
>
> The response echoes your active filters in `meta.filters`, so you can confirm exactly what was applied.

## Filters and paging

Filters are applied while each page is being filled, so pages stay close to your `limit` rather than coming back nearly empty. To get the next page, send the **same filters** again and add the `cursor` from the previous response. Keep going until `hasMore` is `false`.

Invalid values (a bad date, `min_score=11`, `min_score` greater than `max_score`) return `400` with a message explaining what to fix.

To sample the comments behind a mix-bar bucket (evidence, not a full export), see [Retrieving comments](/guides/core-concepts/retrieving-comments).