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.
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:
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.
1. Match your own links
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:
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.
Posts with at least 10 analyzed comments get flags:
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:
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, andcomparison.deltasgives 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. Needscomments:read.include: ["timeline"]— Scores over Time by day, week, or month, by comment date or post date.include: ["languages"]andfilters.languagescover multilingual audiences.
5. Export
Every ready analysis has export.url. Pick a table and a format:
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
See Rate limits.
