Create an analysis from a content selection
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. Responds201withstatus: ready.search.mode: keywordis folded intofilters.keywordsand still returns a201snapshot. - Job (
searchwithmode: ai— the default — or more than 100 posts): responds202withstatus: queuedand aLocationheader. PollGET /analyses/{analysisId}untilstatusisreadyorfailed, honoringRetry-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.
Authentication
Bearer authentication of the form Bearer <token>, where token is your auth token.
Request
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 2–4 sides instead of analyzing one selection. filters
and search apply to every side. Labels default to Side N
and must be unique.
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 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.
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.
Optional extras computed with the analysis: timeline (Scores
over Time), languages (detected comment languages),
wordCloud, emojiCloud.
Options for include: ["timeline"]. Sending timeline without that include is a 400.
Response headers
Host path of the analysis, e.g. /analyst/v1/analyses/an_…
Response
Analysis computed inline (status: ready)
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.
