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

# Create an analysis from a content selection

POST https://api.siftsy.app/analyst/v1/analyses
Content-Type: application/json

Requires `analyses:run`. **Selection → analysis → comments.** Name the
content (`selection.collectionId`, `selection.postIds`, or
`selection.posts` filters — the same filters as `GET /posts`, plus
`tag`), optionally narrow the comments with dashboard `filters`
and/or an AI `search`, and get back one analysis resource.

* **Snapshot** (no AI `search`, ≤ 100 posts): computed inline from
  stored comment scores. Responds `201` with `status: ready`.
  `search.mode: keyword` is folded into `filters.keywords` and still
  returns a `201` snapshot.
* **Job** (`search` with `mode: ai` — the default — or more than
  100 posts): responds `202` with `status: queued` and a `Location`
  header. Poll `GET /analyses/{analysisId}` until `status` is
  `ready` or `failed`, honoring `Retry-After` / `meta.pollAfterMs`.

Either way, a sample of comments behind the analysis is
`GET /analyses/{analysisId}/comments`, and flat tables for a
warehouse or spreadsheet are `GET /analyses/{analysisId}/export`.
Analyses expire after 7 days.

**Compare** (`compare` instead of `selection`): 2–4 sides, each its
own selection (`kind: comparison`). `filters` and `search` apply to
every side. The result is `comparison.sides[]` — each side has the
same `scope` / `content` / `commentAnalysis` as a single analysis —
and `comparison.deltas[]`, each side against side 1. Up to 1,000
distinct posts across all sides.

**Answer** (`answer`): a written finding over the matched comments,
with each claim citing real comments (`[1]`, `[2, 5]`) that resolve
in `commentAnalysis.answer.citations`. Pass `answer.question` for a
direct answer, or `answer: true` for an overview. Always a job. If
the writer fails, the analysis is still `ready` with its numbers and
`answer.error` set. Not available on comparisons.

**Extras** (`include`): `timeline` (Scores over Time by day, week,
or month, by comment date or post date — options in `timeline`),
`languages` (detected comment languages), `wordCloud`, `emojiCloud`.

Links: follow `url` (the analysis), `comments.url`, and `export.url`
as-is — all are absolute URLs on the host you called. The `Location` header is a
path on the host (`/analyst/v1/analyses/{analysisId}`); `comments.path`
is relative to the API base URL (`/analyses/{analysisId}/comments`).
If you join paths yourself, do not prepend `/analyst/v1` to
`comments.path` a second time.
Selections are capped at 1,000 posts (`selectionTruncated: true`
when more matched). Never rescores posts or changes the workspace.

Rate class `analysis_create` (10 / minute, 100 / day per key), or
`analysis_search` (2 / minute, 10 / day) when `search.mode` is `ai`
or an `answer` is requested. Recreate rollups on one refresh a day,
not every run.

Reference: https://api.docs.siftsy.com/api-reference/siftsy-analyst-api/create-analysis

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.
- `X-Api-Key` header (required) — API Key authentication via header

## Servers

- `https://api.siftsy.app/analyst/v1` (Production, default)
- `http://localhost:3000/analyst/v1` (Local development)

## Request

### Body (application/json)

This endpoint expects a CreateAnalysisRequest.

- `selection` (AnalysisSelection, optional) — Which content the analysis covers. Provide exactly one of `postIds` or `posts`; `collectionId` may stand alone or be combined with `posts` filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).
- `compare` (list of AnalysisCompareSide, optional) — Compare 2–4 sides instead of analyzing one selection. `filters` and `search` apply to every side. Labels default to `Side N` and must be unique.
- `filters` (AnalysisFilters, optional) — Comment-level narrowing — the same controls as the dashboard analysis view. Everything is optional; when present, only comments matching **all** active filters count toward the analysis and are returned from `GET /analyses/{analysisId}/comments`. Hidden comments are always excluded.
- `search` (AnalysisSearch, optional) — Search inside the selected comments. `mode: ai` (default) runs the dashboard's semantic search and always creates a job (`202`). `mode: keyword` is deterministic — it is folded into `filters.keywords` and stays synchronous.
- `answer` (AnalysisAnswerRequest, optional) — `true` (or `{}`) writes an overview of what the matched commenters say; `{ question }` writes a direct answer. Every claim cites comments by number. Makes the analysis a job and uses the `analysis_search` rate class. Requires `comments:read` (the answer can quote comments); `403` without it.
- `include` (list of enum, optional) — Optional extras computed with the analysis: `timeline` (Scores over Time), `languages` (detected comment languages), `wordCloud`, `emojiCloud`.
  - Allowed values: `wordCloud`, `emojiCloud`, `timeline`, `languages`
- `timeline` (AnalysisTimelineOptions, optional) — Options for `include: ["timeline"]`. Sending `timeline` without that include is a `400`.

## Response

### 201

Analysis computed inline (`status: ready`)

- `data` (Analysis, optional) — An analysis created with `POST /analyses`. `scope`, `content`, and `commentAnalysis` are `null` until `status` is `ready`. `content` is creator-side (what was posted); `commentAnalysis` is audience-side (how the matched comments landed). A sample of comments behind the analysis lives at `comments.url` (absolute) / `comments.path`; flat tables at `export.url` / `export.path`. A `kind: comparison` analysis has `sides` (the definition) and `comparison` (the result) instead of `scope` / `content` / `commentAnalysis`.
- `meta` (EnvelopeAnalysisMeta, optional)

### 202

Analysis queued (`status: queued`); poll `GET /analyses/{analysisId}`

- `data` (Analysis, optional) — An analysis created with `POST /analyses`. `scope`, `content`, and `commentAnalysis` are `null` until `status` is `ready`. `content` is creator-side (what was posted); `commentAnalysis` is audience-side (how the matched comments landed). A sample of comments behind the analysis lives at `comments.url` (absolute) / `comments.path`; flat tables at `export.url` / `export.path`. A `kind: comparison` analysis has `sides` (the definition) and `comparison` (the result) instead of `scope` / `content` / `commentAnalysis`.
- `meta` (EnvelopeAnalysisMeta, optional)

## Errors

### 400 Bad Request Error

Invalid request

- `any`

### 403 Forbidden Error

Missing required scope

- `any`

### 404 Not Found Error

Resource not found

- `any`

### 429 Too Many Requests Error

A per-minute cap, a per-day budget, or the daily transfer cap was exceeded. `error.message` is `Rate limit exceeded`, `Daily request limit exceeded`, or `Daily transfer limit exceeded`. Honor `Retry-After` (next UTC minute for burst caps; UTC midnight for daily budgets). Sized for a scheduled BI refresh: burst caps that a sequential loop cannot trip, daily budgets that fit eight full refreshes a day of a 500-post workspace or one full refresh plus hourly incrementals. Defaults: 300/minute and 10,000/day globally, with class budgets for per-post comment samples (120/min, 1,000/day), analysis-wide comment samples (20/min, 300/day), collection posts (60/min, 1,000/day), analysis reads (60/min, 2,000/day), analysis create (10/min, 100/day), AI search (2/min, 10/day), adding posts (10/min, 200/day), adding accounts (2/min, 20/day), refreshing posts (10/min, 200/day), and content job polls (60/min, 2,000/day). Daily transfer cap 500 MB.

- `any`

## Types

### AnalysisSelection

Which content the analysis covers. Provide exactly one of `postIds` or `posts`; `collectionId` may stand alone or be combined with `posts` filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).

- `collectionId` (string, optional) — Only posts in this collection (and its sub-collections).
- `postIds` (list of string, optional) — Explicit post ids. Cannot be combined with `collectionId` or `posts`.
- `posts` (map from string to any, optional) — The same filters accepted by `GET /posts`: `link`, `account`, `tag`, `platform`, `posted_since`, `posted_until`, `updated_since`, `min_score` / `max_score`, the bucket percentage ranges (`min_positive_percent`, …), and `status` (`complete` by default).

### AnalysisCompareSide

- `selection` (AnalysisSelection, required) — Which content the analysis covers. Provide exactly one of `postIds` or `posts`; `collectionId` may stand alone or be combined with `posts` filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).
- `label` (string, optional)

### AnalysisFilters

Comment-level narrowing — the same controls as the dashboard analysis view. Everything is optional; when present, only comments matching **all** active filters count toward the analysis and are returned from `GET /analyses/{analysisId}/comments`. Hidden comments are always excluded.

- `sentiment` (list of enum, optional)
  - Allowed values: `positive`, `lean_positive`, `neutral`, `lean_negative`, `negative`
- `content` (list of enum, optional)
  - Allowed values: `positive`, `lean_positive`, `neutral`, `lean_negative`, `negative`
- `topic` (list of enum, optional)
  - Allowed values: `positive`, `lean_positive`, `neutral`, `lean_negative`, `negative`
- `relevance` (list of string, optional) — Bucket names or dashboard labels (`on_topic`, `relevant`, `general`, `off_topic`).
- `consensus` (list of string, optional) — Bucket names or dashboard labels (`agreeing`, `discussing`, `debating`, `fighting`). Consensus is how commenters react to **each other**, not to the post.
- `keywords` (list of string, optional) — Keep comments containing these terms (case-insensitive).
- `keywordMatch` (enum, optional, default: any)
  - Allowed values: `any`, `all`
- `excludeKeywords` (list of string, optional)
- `usernames` (list of string, optional) — Keep comments from these usernames (leading `@` optional).
- `excludeUsernames` (list of string, optional)
- `creator` (enum, optional) — Comments posted by the creator of the post.
  - Allowed values: `include`, `exclude`, `only`
- `replies` (enum, optional)
  - Allowed values: `include`, `exclude`, `only`
- `questions` (enum, optional)
  - Allowed values: `include`, `exclude`, `only`
- `mentions` (enum, optional) — Comments that @-mention someone.
  - Allowed values: `include`, `exclude`, `only`
- `emoji` (enum, optional) — Emoji-only comments.
  - Allowed values: `include`, `exclude`, `only`
- `minLikes` (double, optional)
- `languages` (AnalysisFiltersLanguages, optional) — Comment languages as ISO 639 codes (`en`, `es`, `pt`; region suffixes such as `pt-BR` are read as `pt`). An array is shorthand for `contains`. `contains`: the comment includes any listed language. `only`: every language in the comment is listed. Comments with no detected language never match.
- `since` (datetime, optional) — Comment posted at or after this time.
- `until` (datetime, optional)

### AnalysisSearch

Search inside the selected comments. `mode: ai` (default) runs the dashboard's semantic search and always creates a job (`202`). `mode: keyword` is deterministic — it is folded into `filters.keywords` and stays synchronous.

- `query` (string, required)
- `mode` (enum, optional, default: ai)
  - Allowed values: `ai`, `keyword`
- `minRelevance` (double, optional) — Optional relevance floor for `ai` results (0–10).

### AnalysisAnswerRequest

`true` (or `{}`) writes an overview of what the matched commenters say; `{ question }` writes a direct answer. Every claim cites comments by number. Makes the analysis a job and uses the `analysis_search` rate class. Requires `comments:read` (the answer can quote comments); `403` without it.

- boolean
- AnalysisAnswerRequest1

### AnalysisTimelineOptions

Options for `include: ["timeline"]`. Sending `timeline` without that include is a `400`.

- `granularity` (enum, optional, default: day) — Weeks start Monday. Very long day series come back weekly.
  - Allowed values: `day`, `week`, `month`
- `basis` (enum, optional, default: comment) — `comment` places each comment on the day it was written; `post` on the day its post was published.
  - Allowed values: `comment`, `post`
- `timeZone` (string, optional, default: UTC) — IANA zone for the period boundaries, e.g. `America/New_York`.

### Analysis

An analysis created with `POST /analyses`. `scope`, `content`, and `commentAnalysis` are `null` until `status` is `ready`. `content` is creator-side (what was posted); `commentAnalysis` is audience-side (how the matched comments landed). A sample of comments behind the analysis lives at `comments.url` (absolute) / `comments.path`; flat tables at `export.url` / `export.path`. A `kind: comparison` analysis has `sides` (the definition) and `comparison` (the result) instead of `scope` / `content` / `commentAnalysis`.

- `id` (string, optional)
- `url` (string, optional, nullable) — Absolute URL of this analysis on the host you called. Poll it as-is.
- `kind` (enum, optional)
  - Allowed values: `snapshot`, `search`, `comparison`
- `sides` (list of AnalysisSidesItems, optional) — Comparisons only. The resolved sides, in `compare` order.
- `comparison` (AnalysisComparison, optional, nullable) — Comparisons only, once `ready`.
- `answer` (AnalysisAnswer, optional, nullable) — Echo of `answer` (`{ question }`; `question` is `null` for an overview).
- `timeline` (AnalysisTimelineOptions, optional) — Options for `include: ["timeline"]`. Sending `timeline` without that include is a `400`.
- `export` (AnalysisExport, optional)
- `status` (enum, optional)
  - Allowed values: `queued`, `running`, `ready`, `failed`
- `createdAt` (string, optional)
- `updatedAt` (string, optional, nullable)
- `completedAt` (string, optional, nullable)
- `expiresAt` (string, optional, nullable)
- `selection` (AnalysisSelection, optional) — Which content the analysis covers. Provide exactly one of `postIds` or `posts`; `collectionId` may stand alone or be combined with `posts` filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).
- `filters` (any, optional, nullable) — Echo of the normalized `filters`, or `null`.
- `search` (any, optional, nullable) — Echo of `search` (`query`, `mode`, optional `minRelevance`), or `null`.
- `include` (list of string, optional)
- `postCount` (integer, optional)
- `postIds` (list of string, optional) — Resolved post ids, newest first.
- `selectionTruncated` (boolean, optional) — True when the selection matched more than 1,000 posts.
- `progress` (AnalysisProgress, optional, nullable) — Present while `queued` / `running`.
- `pollAfterMs` (integer, optional, nullable)
- `error` (AnalysisError, optional, nullable) — Present when `status` is `failed`.
- `scope` (AnalysisScope, optional, nullable) — How much of the selection the analysis describes.
- `content` (AnalysisContent, optional, nullable) — Creator-side summary of the selected posts.
- `commentAnalysis` (AnalysisCommentAnalysis, optional) — Audience-side aggregate over the matched comments — the same vibe-check math as the dashboard. `notableComments` lists `{postId, commentId}` pairs. `briefSummary`, `topics`, and `outliers` are reserved (currently `null` / empty); a written finding is `answer`.
- `comments` (AnalysisComments, optional)
- `computedAt` (string, optional, nullable)

### EnvelopeAnalysisMeta

- `status` (enum, optional)
  - Allowed values: `queued`, `running`, `ready`, `failed`
- `pollAfterMs` (integer, optional) — Present while `status` is `queued` or `running`

### AnalysisFiltersLanguages

Comment languages as ISO 639 codes (`en`, `es`, `pt`; region suffixes such as `pt-BR` are read as `pt`). An array is shorthand for `contains`. `contains`: the comment includes any listed language. `only`: every language in the comment is listed. Comments with no detected language never match.

- list of string
- AnalysisFiltersLanguages1

### AnalysisAnswerRequest1

- `question` (string, optional)

### AnalysisSidesItems

- `side` (integer, optional) — 1-based; pass as `?side=` on the comments route
- `label` (string, optional)
- `selection` (AnalysisSelection, optional) — Which content the analysis covers. Provide exactly one of `postIds` or `posts`; `collectionId` may stand alone or be combined with `posts` filters to narrow within the collection. Resolves to at most 1,000 posts (newest first).
- `postCount` (integer, optional)
- `selectionTruncated` (boolean, optional)

### AnalysisComparison

Comparisons only, once `ready`.

- `sides` (list of map from string to any, optional) — One entry per side with `label`, `scope`, `content` (up to 25 post cards), and `commentAnalysis` — the same shapes as a single analysis.
- `deltas` (list of AnalysisComparisonDeltasItems, optional) — Each side after the first against side 1: score points (`scores`), 0–1 share differences (`shareOfComments`, `shareOfContent`), and mix-bar percentage points (`mix`).

### AnalysisAnswer

Present when `answer` was requested. `text` is markdown with citation markers (`[1]`, `[2, 5]`) numbered in reading order; each number is a `citations[].n`. Claims commenters make are attributed, never stated as fact. Links, images, and URLs are removed from `text`. When the writer fails, `text` is `null` and `error` explains; the analysis numbers are still ready. Citations carry comment text and usernames only for keys with `comments:read`. Other keys get `{ n, postId, commentId, postLink }` and `citationsRedacted: true`; they still read `text`, a summary that paraphrases the comments (at most a short quoted fragment).

- `question` (string, optional, nullable)
- `text` (string, optional, nullable)
- `citations` (list of AnalysisAnswerCitationsItems, optional)
- `citationsRedacted` (boolean, optional) — Present (true) when the key lacks `comments:read` and citations are cut to ids.
- `sampleSize` (integer, optional)
- `generatedAt` (string, optional)
- `error` (AnalysisAnswerError, optional)

### AnalysisExport

- `path` (string, optional) — Relative to the API base URL. Add `?table=` and `&format=csv`.
- `url` (string, optional, nullable)

### AnalysisProgress

Present while `queued` / `running`.

- `phase` (string, optional)
- `percent` (double, optional)

### AnalysisError

Present when `status` is `failed`.

- `message` (string, optional)

### AnalysisScope

How much of the selection the analysis describes.

- `postCount` (integer, optional)
- `postIds` (list of string, optional)
- `totalComments` (integer, optional) — Visible comments across the selection before `filters` / `search`.
- `matchedComments` (integer, optional) — Comments that matched `filters` / `search` — the ones the numbers below describe.
- `matchedPosts` (integer, optional)
- `shareOfComments` (double, optional, nullable) — matchedComments / totalComments (0–1).
- `shareOfContent` (double, optional, nullable) — matchedPosts / postCount (0–1).

### AnalysisContent

Creator-side summary of the selected posts.

- `postCount` (integer, optional)
- `posts` (list of map from string to any, optional) — Up to 100 post cards (newest first) with `matchedComments`.
- `postsTruncated` (boolean, optional)
- `topics` (list of AnalysisContentTopicsItems, optional) — Creator topics across the selection, deduped, with `postCount`.
- `messages` (list of AnalysisContentMessagesItems, optional)
- `scores` (AnalysisContentScores, optional)
- `mix` (AnalysisContentMix, optional)

### AnalysisCommentAnalysis

Audience-side aggregate over the matched comments — the same vibe-check math as the dashboard. `notableComments` lists `{postId, commentId}` pairs. `briefSummary`, `topics`, and `outliers` are reserved (currently `null` / empty); a written finding is `answer`.

- `briefSummary` (string, optional, nullable) — Audience brief when materialized on the post
- `scores` (PostScores, optional) — Scores resolved for the team's selected score version (1-10 scale). `content` / `topic` are populated for score version 2+ teams.
- `mix` (AnalysisCommentAnalysisMix, optional)
- `topics` (list of CommentTheme, optional) — Emergent comment themes when stored on the post
- `notableCommentIds` (list of string, optional)
- `outliers` (list of AnalysisCommentAnalysisOutliersItems, optional)
- `wordCloud` (any, optional, nullable)
- `emojiCloud` (any, optional, nullable)
- `totalComments` (double, optional, nullable)
- `completeness` (enum, optional)
  - Allowed values: `full`, `scores_and_content`, `scores_only`, `content_only`, `unavailable`
- `notableComments` (list of AnalysisCommentAnalysisNotableCommentsItems, optional)
- `timeline` (AnalysisTimeline, optional) — Present with `include: ["timeline"]`. Scores over Time with the dashboard chart's bucketing, over the matched comments. Each point's `scores` are the mean 1–10 score of that period's comments and `mix` its five-bucket shares. `lowConfidence` marks periods with fewer than `minComments` comments. `coverage.status` is `insufficient` when too few comments carry a usable timestamp.
- `languages` (AnalysisLanguages, optional) — Present with `include: ["languages"]`. A comment in two languages counts in both, so shares can add up to more than 1. Up to 25 languages, most common first.
- `answer` (AnalysisAnswer, optional) — Present when `answer` was requested. `text` is markdown with citation markers (`[1]`, `[2, 5]`) numbered in reading order; each number is a `citations[].n`. Claims commenters make are attributed, never stated as fact. Links, images, and URLs are removed from `text`. When the writer fails, `text` is `null` and `error` explains; the analysis numbers are still ready. Citations carry comment text and usernames only for keys with `comments:read`. Other keys get `{ n, postId, commentId, postLink }` and `citationsRedacted: true`; they still read `text`, a summary that paraphrases the comments (at most a short quoted fragment).

### AnalysisComments

- `path` (string, optional) — Relative to the API base URL (`…/analyst/v1`).
- `url` (string, optional, nullable) — Absolute URL for `path` on the host you called. Follow it as-is.

### AnalysisFiltersLanguages1

- `contains` (list of string, optional)
- `only` (list of string, optional)

### AnalysisComparisonDeltasItems

- `label` (string, optional)
- `vs` (string, optional)
- `scores` (map from string to double, optional)
- `shareOfComments` (double, optional, nullable)
- `shareOfContent` (double, optional, nullable)
- `mix` (map from string to any, optional)

### AnalysisAnswerCitationsItems

- `n` (integer, optional)
- `postId` (string, optional, nullable)
- `commentId` (string, optional, nullable)
- `username` (string, optional, nullable)
- `likes` (double, optional, nullable)
- `text` (string, optional, nullable)
- `platform` (string, optional, nullable)
- `postLink` (string, optional, nullable)
- `postAccount` (string, optional, nullable)

### AnalysisAnswerError

- `message` (string, optional)

### AnalysisContentTopicsItems

- `title` (string, optional)
- `description` (string, optional, nullable)
- `postCount` (integer, optional)

### AnalysisContentMessagesItems

- `topic` (string, optional)
- `stance` (string, optional, nullable)
- `postCount` (integer, optional)

### AnalysisContentScores

- `content` (double, optional, nullable)
- `topic` (double, optional, nullable)

### AnalysisContentMix

- `content` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `topic` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.

### PostScores

Scores resolved for the team's selected score version (1-10 scale). `content` / `topic` are populated for score version 2+ teams.

- `scoreVersion` (double, optional)
- `siftsyScore` (double, optional, nullable)
- `sentiment` (double, optional, nullable)
- `relevance` (double, optional, nullable)
- `consensus` (double, optional, nullable)
- `content` (double, optional, nullable)
- `topic` (double, optional, nullable)

### AnalysisCommentAnalysisMix

- `sentiment` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `content` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `topic` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `relevance` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.
- `consensus` (ScoreBuckets, optional) — Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.

### CommentTheme

- `label` (string, optional)
- `shareOfComments` (double, optional, nullable)
- `shareOfContent` (double, optional, nullable)
- `commentCount` (double, optional, nullable)
- `postCount` (double, optional, nullable)
- `scores` (PostScores, optional) — Scores resolved for the team's selected score version (1-10 scale). `content` / `topic` are populated for score version 2+ teams.
- `brief` (CommentThemeBrief, optional)
- `sampleCommentIds` (list of string, optional)

### AnalysisCommentAnalysisOutliersItems

### AnalysisCommentAnalysisNotableCommentsItems

- `postId` (string, optional)
- `commentId` (string, optional)

### AnalysisTimeline

Present with `include: ["timeline"]`. Scores over Time with the dashboard chart's bucketing, over the matched comments. Each point's `scores` are the mean 1–10 score of that period's comments and `mix` its five-bucket shares. `lowConfidence` marks periods with fewer than `minComments` comments. `coverage.status` is `insufficient` when too few comments carry a usable timestamp.

- `basis` (enum, optional)
  - Allowed values: `comment`, `post`
- `granularity` (enum, optional)
  - Allowed values: `day`, `week`, `month`
- `monthsFromWeeks` (boolean, optional) — Present (true) on very long series, where months are built from weeks and each week counts in the month of its Monday.
- `timeZone` (string, optional)
- `coverage` (AnalysisTimelineCoverage, optional)
- `minComments` (integer, optional)
- `points` (list of AnalysisTimelinePointsItems, optional)

### AnalysisLanguages

Present with `include: ["languages"]`. A comment in two languages counts in both, so shares can add up to more than 1. Up to 25 languages, most common first.

- `totalComments` (integer, optional)
- `detectedComments` (integer, optional)
- `undetectedComments` (integer, optional)
- `languages` (list of AnalysisLanguagesLanguagesItems, optional)
- `languagesTruncated` (boolean, optional)

### ScoreBuckets

Five-bucket percentage breakdown. Dashboard labels per dimension — Sentiment: Positive / Lean positive / Neutral / Lean negative / Negative. Content: Supportive (positive) / Receptive (leanPositive) / Split (neutral) / Skeptical (leanNegative) / Opposed (negative). Topic: Enthusiastic (positive) / Favorable (leanPositive) / Mixed (neutral) / Critical (leanNegative) / Hostile (negative). Relevance: On-topic (positive) / Relevant (leanPositive) / General (leanNegative) / Off-topic (negative). Consensus: Agreeing (positive) / Discussing (leanPositive) / Debating (leanNegative) / Fighting (negative). neutralPercent is typically unused for relevance and consensus.

- `positivePercent` (double, optional, nullable)
- `leanPositivePercent` (double, optional, nullable)
- `neutralPercent` (double, optional, nullable)
- `leanNegativePercent` (double, optional, nullable)
- `negativePercent` (double, optional, nullable)

### CommentThemeBrief

- `heading` (string, optional, nullable)
- `description` (string, optional, nullable)

### AnalysisTimelineCoverage

- `total` (integer, optional)
- `timed` (integer, optional)
- `approximate` (integer, optional)
- `untimed` (integer, optional)
- `status` (enum, optional)
  - Allowed values: `complete`, `partial`, `insufficient`, `none`

### AnalysisTimelinePointsItems

- `period` (string, optional) — Period start, `YYYY-MM-DD`
- `comments` (integer, optional)
- `lowConfidence` (boolean, optional)
- `scores` (AnalysisTimelinePointsItemsScores, optional)
- `mix` (map from string to ScoreBuckets, optional)

### AnalysisLanguagesLanguagesItems

- `language` (string, optional)
- `comments` (integer, optional)
- `shareOfComments` (double, optional, nullable)

### AnalysisTimelinePointsItemsScores

- `sentiment` (double, optional, nullable)
- `content` (double, optional, nullable)
- `topic` (double, optional, nullable)
- `relevance` (double, optional, nullable)
- `consensus` (double, optional, nullable)

## Examples

### Filtered posts, negative on-topic comments only

**Request**

```json
{
  "selection": {
    "posts": {
      "account": "@acme",
      "platform": "tiktok",
      "posted_since": "2026-08-01"
    }
  },
  "filters": {
    "sentiment": [
      "negative",
      "lean_negative"
    ],
    "relevance": [
      "on_topic",
      "relevant"
    ],
    "replies": "exclude"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python Filtered posts, negative on-topic comments only
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "posts": {
            "account": "@acme",
            "platform": "tiktok",
            "posted_since": "2026-08-01"
        } },
    "filters": {
        "sentiment": ["negative", "lean_negative"],
        "relevance": ["on_topic", "relevant"],
        "replies": "exclude"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Filtered posts, negative on-topic comments only
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"posts":{"account":"@acme","platform":"tiktok","posted_since":"2026-08-01"}},"filters":{"sentiment":["negative","lean_negative"],"relevance":["on_topic","relevant"],"replies":"exclude"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Filtered posts, negative on-topic comments only
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@acme\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2026-08-01\"\n    }\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ],\n    \"relevance\": [\n      \"on_topic\",\n      \"relevant\"\n    ],\n    \"replies\": \"exclude\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Filtered posts, negative on-topic comments only
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@acme\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2026-08-01\"\n    }\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ],\n    \"relevance\": [\n      \"on_topic\",\n      \"relevant\"\n    ],\n    \"replies\": \"exclude\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Filtered posts, negative on-topic comments only
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@acme\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2026-08-01\"\n    }\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ],\n    \"relevance\": [\n      \"on_topic\",\n      \"relevant\"\n    ],\n    \"replies\": \"exclude\"\n  }\n}")
  .asString();
```

```php Filtered posts, negative on-topic comments only
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "posts": {
      "account": "@acme",
      "platform": "tiktok",
      "posted_since": "2026-08-01"
    }
  },
  "filters": {
    "sentiment": [
      "negative",
      "lean_negative"
    ],
    "relevance": [
      "on_topic",
      "relevant"
    ],
    "replies": "exclude"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Filtered posts, negative on-topic comments only
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@acme\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2026-08-01\"\n    }\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ],\n    \"relevance\": [\n      \"on_topic\",\n      \"relevant\"\n    ],\n    \"replies\": \"exclude\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Filtered posts, negative on-topic comments only
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["posts": [
      "account": "@acme",
      "platform": "tiktok",
      "posted_since": "2026-08-01"
    ]],
  "filters": [
    "sentiment": ["negative", "lean_negative"],
    "relevance": ["on_topic", "relevant"],
    "replies": "exclude"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### AI search inside a collection (job)

**Request**

```json
{
  "selection": {
    "collectionId": "col_launch"
  },
  "search": {
    "query": "complaints about shipping or delivery"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python AI search inside a collection (job)
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "collectionId": "col_launch" },
    "search": { "query": "complaints about shipping or delivery" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript AI search inside a collection (job)
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"collectionId":"col_launch"},"search":{"query":"complaints about shipping or delivery"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go AI search inside a collection (job)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"search\": {\n    \"query\": \"complaints about shipping or delivery\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby AI search inside a collection (job)
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"search\": {\n    \"query\": \"complaints about shipping or delivery\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java AI search inside a collection (job)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"search\": {\n    \"query\": \"complaints about shipping or delivery\"\n  }\n}")
  .asString();
```

```php AI search inside a collection (job)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "collectionId": "col_launch"
  },
  "search": {
    "query": "complaints about shipping or delivery"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp AI search inside a collection (job)
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"search\": {\n    \"query\": \"complaints about shipping or delivery\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift AI search inside a collection (job)
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["collectionId": "col_launch"],
  "search": ["query": "complaints about shipping or delivery"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Dove brand + influencer posts, PR / ambassador asks (job)

**Request**

```json
{
  "selection": {
    "posts": {
      "account": "@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty",
      "platform": "tiktok",
      "posted_since": "2025-12-01"
    }
  },
  "filters": {
    "creator": "exclude",
    "replies": "exclude"
  },
  "search": {
    "query": "asking for PR packages, free samples, or to become a Dove ambassador or UGC creator",
    "minRelevance": 6
  }
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python Dove brand + influencer posts, PR / ambassador asks (job)
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "posts": {
            "account": "@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty",
            "platform": "tiktok",
            "posted_since": "2025-12-01"
        } },
    "filters": {
        "creator": "exclude",
        "replies": "exclude"
    },
    "search": {
        "query": "asking for PR packages, free samples, or to become a Dove ambassador or UGC creator",
        "minRelevance": 6
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Dove brand + influencer posts, PR / ambassador asks (job)
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"posts":{"account":"@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty","platform":"tiktok","posted_since":"2025-12-01"}},"filters":{"creator":"exclude","replies":"exclude"},"search":{"query":"asking for PR packages, free samples, or to become a Dove ambassador or UGC creator","minRelevance":6}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Dove brand + influencer posts, PR / ambassador asks (job)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2025-12-01\"\n    }\n  },\n  \"filters\": {\n    \"creator\": \"exclude\",\n    \"replies\": \"exclude\"\n  },\n  \"search\": {\n    \"query\": \"asking for PR packages, free samples, or to become a Dove ambassador or UGC creator\",\n    \"minRelevance\": 6\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Dove brand + influencer posts, PR / ambassador asks (job)
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2025-12-01\"\n    }\n  },\n  \"filters\": {\n    \"creator\": \"exclude\",\n    \"replies\": \"exclude\"\n  },\n  \"search\": {\n    \"query\": \"asking for PR packages, free samples, or to become a Dove ambassador or UGC creator\",\n    \"minRelevance\": 6\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Dove brand + influencer posts, PR / ambassador asks (job)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2025-12-01\"\n    }\n  },\n  \"filters\": {\n    \"creator\": \"exclude\",\n    \"replies\": \"exclude\"\n  },\n  \"search\": {\n    \"query\": \"asking for PR packages, free samples, or to become a Dove ambassador or UGC creator\",\n    \"minRelevance\": 6\n  }\n}")
  .asString();
```

```php Dove brand + influencer posts, PR / ambassador asks (job)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "posts": {
      "account": "@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty",
      "platform": "tiktok",
      "posted_since": "2025-12-01"
    }
  },
  "filters": {
    "creator": "exclude",
    "replies": "exclude"
  },
  "search": {
    "query": "asking for PR packages, free samples, or to become a Dove ambassador or UGC creator",
    "minRelevance": 6
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Dove brand + influencer posts, PR / ambassador asks (job)
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"posts\": {\n      \"account\": \"@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty\",\n      \"platform\": \"tiktok\",\n      \"posted_since\": \"2025-12-01\"\n    }\n  },\n  \"filters\": {\n    \"creator\": \"exclude\",\n    \"replies\": \"exclude\"\n  },\n  \"search\": {\n    \"query\": \"asking for PR packages, free samples, or to become a Dove ambassador or UGC creator\",\n    \"minRelevance\": 6\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Dove brand + influencer posts, PR / ambassador asks (job)
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["posts": [
      "account": "@dove,@skinbysam,@thescrubgirl,@jessdoesbeauty",
      "platform": "tiktok",
      "posted_since": "2025-12-01"
    ]],
  "filters": [
    "creator": "exclude",
    "replies": "exclude"
  ],
  "search": [
    "query": "asking for PR packages, free samples, or to become a Dove ambassador or UGC creator",
    "minRelevance": 6
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Brand vs competitor, last 30 days (sync when ≤ 100 posts)

**Request**

```json
{
  "compare": [
    {
      "selection": {
        "posts": {
          "account": "@dove",
          "posted_since": "2026-08-29"
        }
      },
      "label": "Dove"
    },
    {
      "selection": {
        "posts": {
          "account": "@olay",
          "posted_since": "2026-08-29"
        }
      },
      "label": "Olay"
    }
  ],
  "filters": {
    "creator": "exclude"
  },
  "include": [
    "timeline"
  ],
  "timeline": {
    "granularity": "week",
    "basis": "comment",
    "timeZone": "America/New_York"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python Brand vs competitor, last 30 days (sync when ≤ 100 posts)
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "compare": [
        {
            "selection": { "posts": {
                    "account": "@dove",
                    "posted_since": "2026-08-29"
                } },
            "label": "Dove"
        },
        {
            "selection": { "posts": {
                    "account": "@olay",
                    "posted_since": "2026-08-29"
                } },
            "label": "Olay"
        }
    ],
    "filters": { "creator": "exclude" },
    "include": ["timeline"],
    "timeline": {
        "granularity": "week",
        "basis": "comment",
        "timeZone": "America/New_York"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Brand vs competitor, last 30 days (sync when ≤ 100 posts)
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"compare":[{"selection":{"posts":{"account":"@dove","posted_since":"2026-08-29"}},"label":"Dove"},{"selection":{"posts":{"account":"@olay","posted_since":"2026-08-29"}},"label":"Olay"}],"filters":{"creator":"exclude"},"include":["timeline"],"timeline":{"granularity":"week","basis":"comment","timeZone":"America/New_York"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Brand vs competitor, last 30 days (sync when ≤ 100 posts)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"compare\": [\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@dove\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Dove\"\n    },\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@olay\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Olay\"\n    }\n  ],\n  \"filters\": {\n    \"creator\": \"exclude\"\n  },\n  \"include\": [\n    \"timeline\"\n  ],\n  \"timeline\": {\n    \"granularity\": \"week\",\n    \"basis\": \"comment\",\n    \"timeZone\": \"America/New_York\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Brand vs competitor, last 30 days (sync when ≤ 100 posts)
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"compare\": [\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@dove\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Dove\"\n    },\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@olay\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Olay\"\n    }\n  ],\n  \"filters\": {\n    \"creator\": \"exclude\"\n  },\n  \"include\": [\n    \"timeline\"\n  ],\n  \"timeline\": {\n    \"granularity\": \"week\",\n    \"basis\": \"comment\",\n    \"timeZone\": \"America/New_York\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Brand vs competitor, last 30 days (sync when ≤ 100 posts)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"compare\": [\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@dove\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Dove\"\n    },\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@olay\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Olay\"\n    }\n  ],\n  \"filters\": {\n    \"creator\": \"exclude\"\n  },\n  \"include\": [\n    \"timeline\"\n  ],\n  \"timeline\": {\n    \"granularity\": \"week\",\n    \"basis\": \"comment\",\n    \"timeZone\": \"America/New_York\"\n  }\n}")
  .asString();
```

```php Brand vs competitor, last 30 days (sync when ≤ 100 posts)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "compare": [
    {
      "selection": {
        "posts": {
          "account": "@dove",
          "posted_since": "2026-08-29"
        }
      },
      "label": "Dove"
    },
    {
      "selection": {
        "posts": {
          "account": "@olay",
          "posted_since": "2026-08-29"
        }
      },
      "label": "Olay"
    }
  ],
  "filters": {
    "creator": "exclude"
  },
  "include": [
    "timeline"
  ],
  "timeline": {
    "granularity": "week",
    "basis": "comment",
    "timeZone": "America/New_York"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Brand vs competitor, last 30 days (sync when ≤ 100 posts)
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"compare\": [\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@dove\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Dove\"\n    },\n    {\n      \"selection\": {\n        \"posts\": {\n          \"account\": \"@olay\",\n          \"posted_since\": \"2026-08-29\"\n        }\n      },\n      \"label\": \"Olay\"\n    }\n  ],\n  \"filters\": {\n    \"creator\": \"exclude\"\n  },\n  \"include\": [\n    \"timeline\"\n  ],\n  \"timeline\": {\n    \"granularity\": \"week\",\n    \"basis\": \"comment\",\n    \"timeZone\": \"America/New_York\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Brand vs competitor, last 30 days (sync when ≤ 100 posts)
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "compare": [
    [
      "selection": ["posts": [
          "account": "@dove",
          "posted_since": "2026-08-29"
        ]],
      "label": "Dove"
    ],
    [
      "selection": ["posts": [
          "account": "@olay",
          "posted_since": "2026-08-29"
        ]],
      "label": "Olay"
    ]
  ],
  "filters": ["creator": "exclude"],
  "include": ["timeline"],
  "timeline": [
    "granularity": "week",
    "basis": "comment",
    "timeZone": "America/New_York"
  ]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Cited answer to a question (job)

**Request**

```json
{
  "selection": {
    "collectionId": "col_launch"
  },
  "filters": {
    "sentiment": [
      "negative",
      "lean_negative"
    ]
  },
  "answer": {
    "question": "What is driving the negative comments?"
  }
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python Cited answer to a question (job)
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "collectionId": "col_launch" },
    "filters": { "sentiment": ["negative", "lean_negative"] },
    "answer": { "question": "What is driving the negative comments?" }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Cited answer to a question (job)
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"collectionId":"col_launch"},"filters":{"sentiment":["negative","lean_negative"]},"answer":{"question":"What is driving the negative comments?"}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Cited answer to a question (job)
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ]\n  },\n  \"answer\": {\n    \"question\": \"What is driving the negative comments?\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Cited answer to a question (job)
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ]\n  },\n  \"answer\": {\n    \"question\": \"What is driving the negative comments?\"\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java Cited answer to a question (job)
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ]\n  },\n  \"answer\": {\n    \"question\": \"What is driving the negative comments?\"\n  }\n}")
  .asString();
```

```php Cited answer to a question (job)
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "collectionId": "col_launch"
  },
  "filters": {
    "sentiment": [
      "negative",
      "lean_negative"
    ]
  },
  "answer": {
    "question": "What is driving the negative comments?"
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Cited answer to a question (job)
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"filters\": {\n    \"sentiment\": [\n      \"negative\",\n      \"lean_negative\"\n    ]\n  },\n  \"answer\": {\n    \"question\": \"What is driving the negative comments?\"\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Cited answer to a question (job)
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["collectionId": "col_launch"],
  "filters": ["sentiment": ["negative", "lean_negative"]],
  "answer": ["question": "What is driving the negative comments?"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Spanish-language comments only, with language breakdown

**Request**

```json
{
  "selection": {
    "collectionId": "col_latam"
  },
  "filters": {
    "languages": {
      "contains": [
        "es"
      ]
    }
  },
  "include": [
    "languages"
  ]
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python Spanish-language comments only, with language breakdown
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "collectionId": "col_latam" },
    "filters": { "languages": { "contains": ["es"] } },
    "include": ["languages"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Spanish-language comments only, with language breakdown
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"collectionId":"col_latam"},"filters":{"languages":{"contains":["es"]}},"include":["languages"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Spanish-language comments only, with language breakdown
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"collectionId\": \"col_latam\"\n  },\n  \"filters\": {\n    \"languages\": {\n      \"contains\": [\n        \"es\"\n      ]\n    }\n  },\n  \"include\": [\n    \"languages\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Spanish-language comments only, with language breakdown
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"collectionId\": \"col_latam\"\n  },\n  \"filters\": {\n    \"languages\": {\n      \"contains\": [\n        \"es\"\n      ]\n    }\n  },\n  \"include\": [\n    \"languages\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java Spanish-language comments only, with language breakdown
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"collectionId\": \"col_latam\"\n  },\n  \"filters\": {\n    \"languages\": {\n      \"contains\": [\n        \"es\"\n      ]\n    }\n  },\n  \"include\": [\n    \"languages\"\n  ]\n}")
  .asString();
```

```php Spanish-language comments only, with language breakdown
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "collectionId": "col_latam"
  },
  "filters": {
    "languages": {
      "contains": [
        "es"
      ]
    }
  },
  "include": [
    "languages"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Spanish-language comments only, with language breakdown
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"collectionId\": \"col_latam\"\n  },\n  \"filters\": {\n    \"languages\": {\n      \"contains\": [\n        \"es\"\n      ]\n    }\n  },\n  \"include\": [\n    \"languages\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Spanish-language comments only, with language breakdown
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["collectionId": "col_latam"],
  "filters": ["languages": ["contains": ["es"]]],
  "include": ["languages"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 7

**Request**

```json
{
  "selection": {
    "collectionId": "col_launch"
  },
  "include": [
    "wordCloud"
  ]
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "collectionId": "col_launch" },
    "include": ["wordCloud"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"collectionId":"col_launch"},"include":["wordCloud"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "collectionId": "col_launch"
  },
  "include": [
    "wordCloud"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["collectionId": "col_launch"],
  "include": ["wordCloud"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```

### Example 8

**Request**

```json
{
  "selection": {
    "collectionId": "col_launch"
  },
  "include": [
    "wordCloud"
  ]
}
```

**Response**

```json
{
  "data": {
    "id": "an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70",
    "kind": "snapshot",
    "status": "ready",
    "createdAt": "2026-09-10T15:04:05.000Z",
    "updatedAt": "2026-09-10T15:04:05.400Z",
    "completedAt": "2026-09-10T15:04:05.400Z",
    "expiresAt": "2026-09-17T15:04:05.000Z",
    "selection": {
      "collectionId": "col_launch",
      "type": "collection",
      "status": "complete"
    },
    "filters": null,
    "search": null,
    "include": [
      "wordCloud"
    ],
    "postCount": 12,
    "postIds": [
      "p_301",
      "p_298",
      "p_290"
    ],
    "selectionTruncated": false,
    "scope": {
      "postCount": 12,
      "postIds": [
        "p_301",
        "p_298",
        "p_290"
      ],
      "totalComments": 4820,
      "matchedComments": 611,
      "matchedPosts": 11,
      "shareOfComments": 0.1268,
      "shareOfContent": 0.9167
    },
    "content": {
      "postCount": 12,
      "posts": [
        {
          "id": "p_301",
          "platform": "tiktok",
          "link": "https://www.tiktok.com/@acme/video/7311",
          "creator": {
            "username": "acme"
          },
          "postedAt": "2026-09-02T17:00:00.000Z",
          "matchedComments": 97
        }
      ],
      "postsTruncated": false,
      "topics": [
        {
          "title": "Product launch",
          "description": null,
          "postCount": 12
        }
      ],
      "messages": [
        {
          "topic": "Product launch",
          "stance": "The new line ships faster",
          "postCount": 8
        }
      ],
      "scores": {
        "content": 7.1,
        "topic": 6.4
      },
      "mix": {
        "content": {
          "positivePercent": 41,
          "leanPositivePercent": 22,
          "neutralPercent": 18,
          "leanNegativePercent": 11,
          "negativePercent": 8
        },
        "topic": {
          "positivePercent": 35,
          "leanPositivePercent": 27,
          "neutralPercent": 20,
          "leanNegativePercent": 10,
          "negativePercent": 8
        }
      }
    },
    "commentAnalysis": {
      "briefSummary": null,
      "scores": {
        "scoreVersion": 3,
        "siftsyScore": 3.4,
        "sentiment": 2.3,
        "relevance": 7.8,
        "consensus": 6.9,
        "content": 2.1,
        "topic": 2.6
      },
      "mix": {
        "sentiment": {
          "positivePercent": 0,
          "leanPositivePercent": 0,
          "neutralPercent": 0,
          "leanNegativePercent": 38,
          "negativePercent": 62
        },
        "content": {
          "positivePercent": 0,
          "leanPositivePercent": 2,
          "neutralPercent": 5,
          "leanNegativePercent": 40,
          "negativePercent": 53
        },
        "topic": {
          "positivePercent": 1,
          "leanPositivePercent": 3,
          "neutralPercent": 6,
          "leanNegativePercent": 41,
          "negativePercent": 49
        },
        "relevance": {
          "positivePercent": 58,
          "leanPositivePercent": 24,
          "neutralPercent": 9,
          "leanNegativePercent": 6,
          "negativePercent": 3
        },
        "consensus": {
          "positivePercent": 44,
          "leanPositivePercent": 31,
          "neutralPercent": 12,
          "leanNegativePercent": 9,
          "negativePercent": 4
        }
      },
      "topics": [],
      "outliers": [],
      "wordCloud": [
        {
          "text": "shipping",
          "value": 84,
          "type": "word",
          "avgSentiment": 2.1,
          "sentimentCategory": "negative",
          "mentionPercentage": 13.7
        },
        {
          "text": "never arrived",
          "value": 51,
          "type": "phrase",
          "avgSentiment": 1.8,
          "sentimentCategory": "negative",
          "mentionPercentage": 5.6
        }
      ],
      "emojiCloud": null,
      "totalComments": 611,
      "completeness": "scores_and_content",
      "notableComments": [
        {
          "postId": "p_301",
          "commentId": "c_77f1"
        },
        {
          "postId": "p_298",
          "commentId": "c_1a09"
        }
      ]
    },
    "comments": {
      "path": "/analyses/an_5f2c9a1e0b6d4d0f9c1a2b3c4d5e6f70/comments"
    },
    "computedAt": "2026-09-10T15:04:05.400Z"
  },
  "meta": {
    "status": "queued",
    "pollAfterMs": 1
  }
}
```

**SDK Code**

```python
import requests

url = "https://api.siftsy.app/analyst/v1/analyses"

payload = {
    "selection": { "collectionId": "col_launch" },
    "include": ["wordCloud"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://api.siftsy.app/analyst/v1/analyses';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"selection":{"collectionId":"col_launch"},"include":["wordCloud"]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.siftsy.app/analyst/v1/analyses"

	payload := strings.NewReader("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby
require 'uri'
require 'net/http'

url = URI("https://api.siftsy.app/analyst/v1/analyses")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}"

response = http.request(request)
puts response.read_body
```

```java
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.siftsy.app/analyst/v1/analyses")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}")
  .asString();
```

```php
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.siftsy.app/analyst/v1/analyses', [
  'body' => '{
  "selection": {
    "collectionId": "col_launch"
  },
  "include": [
    "wordCloud"
  ]
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp
using RestSharp;

var client = new RestClient("https://api.siftsy.app/analyst/v1/analyses");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"selection\": {\n    \"collectionId\": \"col_launch\"\n  },\n  \"include\": [\n    \"wordCloud\"\n  ]\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "selection": ["collectionId": "col_launch"],
  "include": ["wordCloud"]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.siftsy.app/analyst/v1/analyses")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```