Analyses
An analysis is Siftsy’s answer to “what did the audience say about this content?” It is always computed over a content selection, it always has two sides, and it always has comments underneath it.
What an analysis is
Every analysis pairs the creator side with the audience side:
The relationship between the two is the analysis. A post whose content scores well but whose comment analysis is skeptical is a message that did not land; a post with hostile topic sentiment but agreeing consensus is an audience united against the subject, not against the creator. Comment bodies are deliberately not on the analysis — they live one level down at comments.path as a sample of evidence, so an analysis stays small and you are not exporting the thread.
Consensus is not agreement with the post. Sentiment, content, and topic describe how commenters feel about the post, creator, or subject. Consensus describes how they react to each other. See Scores.
Kinds of analysis
Snapshots, searches, and reports all share the /analyses routes and the same comments.path pattern. kind and status on each row tell you which you are looking at.
Narrowing an analysis
An analysis over all comments in a selection is the baseline. Most questions are about a subset, and there are two ways to name one:
- Filters are structural — a comment either matches or it does not. Mix-bar buckets (
sentiment: ["negative"]), keywords, usernames, creator comments, replies, questions, mentions, emoji-only, a likes floor, a date range. They are the dashboard analysis-view controls, evaluated with the same code, so a filtered analysis here matches what a teammate sees when they click the same bars. - Search is semantic — “comments asking where to buy it” — and needs a model to decide what matches.
mode: airuns the dashboard’s search;mode: keywordis the deterministic fallback.
Either way the result is the same shape. The analysis numbers describe only the matched comments, and scope tells you how big that subset is relative to the whole selection:
Read those two shares together. A theme at 13% of comments spread across 92% of posts is a broad, low-intensity current; the same 13% concentrated on 2 of 12 posts is a flashpoint.
Why some analyses are jobs
Snapshots aggregate scores Siftsy already stored — no model runs, and up to 100 posts they finish inside the request. AI search has to read every selected comment through a language model, and very large selections have to be loaded and filtered before any math happens. Those cannot reliably finish in one HTTP round-trip, so they run in the background.
Rather than two APIs, there is one resource with a status: queued → running → ready | failed. A 201 means the analysis is already ready; a 202 means poll GET /analyses/{id} (honoring Retry-After) until it is. The payload is identical once ready, and both kinds persist for 7 days and serve GET /analyses/{id}/comments from the same stored definition. Details are in the Jobs section below.
The comments underneath
GET /analyses/{id}/comments returns a sample of comments behind the analysis — after its own filters and search matches have been applied — not the full matched set and not the raw thread. Pass source=notables (engagement + relevance), content (grouped onto creator topics/messages), or all (union). Mix-bar query filters narrow that sample further.
Siftsy is an analysis platform, not a comment exporter. Use this route for evidence. Do not use it to dump full comment sections.
See Retrieving comments.
Reference: POST /analyses
POST /analyses runs the selection → analysis → comments flow as an API call:
Requires the analyses:run scope to create, analyses:read to read, and comments:read for comments. Nothing here rescores posts or changes your workspace; analyses are computed from stored comment scores and expire after 7 days.
1. Select content
selection names the posts — see Content selection for the concept. Use exactly one style (a collection may additionally be narrowed with posts filters):
posts.status defaults to complete. Selections resolve newest first and stop at 1,000 posts — selectionTruncated: true tells you when more matched. A selection that matches nothing returns 400.
2. Filter the comments (optional)
filters are the dashboard analysis-view controls. Only comments matching all active filters count toward the analysis, and the comments sample is drawn from that matched set. Hidden comments are always excluded.
Consensus is not agreement with the post. It measures how commenters react to each other. consensus: ["fighting"] returns comments arguing with other commenters, whatever they think of the post.
search looks for meaning inside the selected comments:
mode: "ai"(default) is the dashboard’s semantic search. It always runs as a job.mode: "keyword"is deterministic: the query is folded intofilters.keywordsand the analysis stays synchronous.
include adds optional extras computed from the matched comments: ["wordCloud", "emojiCloud"].
3. Read the analysis
The response is one Analysis resource. status is the only thing that changes between a snapshot and a job:
Poll GET /analyses/{analysisId} until the status is terminal. Non-terminal responses carry Retry-After (seconds) and meta.pollAfterMs; progress.phase and progress.percent describe where the job is. A failed analysis has error.message.
Payload, field by field
4. Sample the comments
GET /analyses/{analysisId}/comments returns a sample of the comments the analysis describes — not the full matchedComments set and not the raw thread. The analysis’s own filters and search matches are applied first, then source=notables|content|all picks the evidence. Mix-bar query filters narrow that sample further. See Retrieving comments.
Until the analysis is ready this route returns 409 with error.message of analysis_not_ready (honor Retry-After) or analysis_failed.
Jobs: when and why
Some analyses are instant and some are not, so the API treats them the same way and lets status tell you which you got.
- Snapshots aggregate scores Siftsy already stored — no model runs. Up to 100 posts, they finish inside the request and come back
201 ready. There is nothing to poll. - Jobs are needed when the work is too slow or too variable for a single HTTP request: AI search runs the language model over every selected comment, and large selections (hundreds of posts, tens of thousands of comments) have to be loaded and filtered first. These return
202 queuedimmediately and finish in the background.
Because the resource is identical in both cases, a client can always follow the same loop:
Snapshots are not stored any less carefully than jobs — both persist for 7 days, appear in GET /analyses, and serve a comments sample from the same stored definition, so a dashboard that fetched an analysis once can keep sampling evidence without recomputing.
Worked example: Dove and Dove influencers
A Dove workspace has two collections: Dove Brand Latest — five TikTok posts from the official @dove account (holiday scrubs, a Dove x Crumbl collab at Walmart, scent layering, deodorant ASMR) — and Dove Influencers, the creator posts made for the same push. The walk-through below runs the full selection → analysis → comments loop against them. Brand-side figures come from Siftsy’s sample workspace; influencer-side figures are illustrative.
Find the selections
The brand collection is the same thing as a post filter on the account — either selection works:
Snapshot the brand collection (sync)
Five posts, no search — this is a snapshot and returns 201 ready inline.
Reading it: the audience is warm (93% positive or lean-positive, no strongly negative bar), on-topic, and agreeing with each other. The word cloud already hints at what they are agreeing about — please, uk, deodorant spray: requests, not complaints.
Narrow to availability requests (filtered snapshot)
The dashboard would answer “how much of this is people asking where to buy it?” by filtering. Same thing here, and the analysis numbers describe only the matched comments:
18% of the brand conversation is regional-availability asks, concentrated on the extrovert/introvert scrub video (18 of its 47 comments). Sentiment dips (6.1 vs 7.0) but consensus climbs — commenters are piling on in agreement that they want it shipped to them.
Search brand + influencers for PR and ambassador asks (job)
Now the question the influencer team cares about: across both collections, who is asking to be sent product or to work with Dove? That needs the AI search, so the request queues.
Poll the Location until it settles:
On the brand posts alone, PR/ambassador asks are ~22% of comments (28 of 128) and 89% positive; the influencer posts dilute that share but add far more absolute volume — which is the list the partnerships team actually wants.
Pull the comments behind it
The comments route applies the search matches first, then returns a sample of those 131 comments — not the full set. Ask for notables:
That sample is the intended use. Totals and mix live on the analysis (scope, commentAnalysis); do not page this route to reconstruct the thread. Mix-bar filters (?consensus=fighting) narrow the sample further.
Everything above is three request shapes — a selection, an analysis body, and a comments sample — applied to two collections. The same calls work for any brand and creator roster in your workspace.
Listing
GET /analyses?kind=all|snapshot|search|report lists newest first. snapshot and search are analyses you created here (with status, postCount, totalComments, matchedComments). report rows are campaign reports saved in Siftsy; they are always ready and expose the stored report at GET /analyses/{id}.
Limits
POST /analysesis on theanalysis_createclass (10 / minute, 100 / day), oranalysis_searchwhensearch.modeisai(2 / minute, 10 / day).GET /analyses/{id}isanalysis_read(60 / minute, 2,000 / day).GET /analyses/{id}/commentsisanalysis_comments(20 / minute, 300 / day) — every page re-reads the comments of every post on the analysis, so take onesource=notablessample per analysis rather than paging through it. See Rate limits.- 1,000 posts per selection; 100 posts for the synchronous path.
- 50 values per list filter, 120 characters per keyword, 300 characters per search query.
- Analyses expire 7 days after creation and return
404afterwards.