Skip to navigation

Exploring and exporting

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

Typical passes:

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

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

Join keys

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

KeyWhat it is
postIdSiftsy post id. Feeds selection.postIds
linkThe post URL as stored
platformtiktok, instagram, youtube, …
accountCreator handle, lowercase, without @ — the same key as by: account breakdown groups
postedAtISO-8601 publish time
collectionIds, tagsCampaigns / groups and content tags the post is in

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

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

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

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

2. Scan for what stands out

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

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

Posts with at least 10 analyzed comments get flags:

FlagRule
negative_sentimentSentiment under 4.5
below_baseline / above_baselineSentiment 1.5+ below / above the selection baseline
commenters_arguing25%+ of comments in the debating or fighting consensus bands
off_topicRelevance under 4.5 — the post is being used as a venue for something else
content_topic_gapContent and topic scores 2+ points apart — the audience likes the creator but not the subject, or the reverse
high_engagement_negativeEngagement rate in the selection’s top quarter while sentiment is negative

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

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

3. Break it down

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

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

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

4. Analyze, compare, answer

Once you know where to look, POST /analyses reads the comments themselves. Three options are built for this workflow:

  • compare — 2–4 sides, each its own selection: brand vs competitor, this month vs last, campaign A vs B. Filters and search apply to every side, and comparison.deltas gives each side against side 1.
  • answer — a written finding with every claim citing real comments. The citations resolve to author, likes, and post link, so a quote in your report traces back to the comment. Needs comments:read.
  • include: ["timeline"] — Scores over Time by day, week, or month, by comment date or post date. include: ["languages"] and filters.languages cover multilingual audiences.
curl -sS -X POST -H "Authorization: Bearer $SIFTSY_API_KEY" -H "Content-Type: application/json" \
https://api.siftsy.app/analyst/v1/analyses \
-d '{ "compare": [
{ "label": "Dove", "selection": { "posts": { "account": "@dove", "posted_since": "2026-08-29" } } },
{ "label": "Olay", "selection": { "posts": { "account": "@olay", "posted_since": "2026-08-29" } } }
],
"filters": { "creator": "exclude" },
"include": ["timeline"], "timeline": { "granularity": "week" } }'

5. Export

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

TableRows
postsOne per post: join keys, stored scores, and matchedComments for this analysis
sidesOne per comparison side, with deltas against side 1
timelineOne per period (and per side)
languagesOne per language (and per side)
citationsThe comments behind answer (needs comments:read)
curl -sS -H "Authorization: Bearer $SIFTSY_API_KEY" \
"https://api.siftsy.app/analyst/v1/analyses/an_…/export?table=posts&format=csv" -o dove_posts.csv

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

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

Rate classes

RouteClassBudget per key
POST /posts/matchposts_match20 / minute, 500 / day
POST /posts/scanposts_scan20 / minute, 500 / day
POST /breakdownsbreakdowns20 / minute, 500 / day
GET /analyses/{id}/exportanalysis_export30 / minute, 500 / day
POST /analyses with answeranalysis_search2 / minute, 10 / day

See Rate limits.