Skip to navigation

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

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

OR
X-Api-Keystring
API Key authentication via header

Request

This endpoint expects an object.
selectionobjectOptional

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

comparelist of objectsOptional

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.

filtersobjectOptional

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.

searchobjectOptional

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.

answerboolean or objectOptional

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.

includelist of enumsOptional

Optional extras computed with the analysis: timeline (Scores over Time), languages (detected comment languages), wordCloud, emojiCloud.

Allowed values:
timelineobjectOptional

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

Response headers

LocationstringOptional

Host path of the analysis, e.g. /analyst/v1/analyses/an_…

Response

Analysis computed inline (status: ready)

dataobjectOptional

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.

metaobjectOptional

Errors

400
Bad Request Error
403
Forbidden Error
404
Not Found Error
429
Too Many Requests Error