Skip to navigation

Scan a selection for posts that stand out

Requires posts:read. One row per post across a selection (up to 1,000 posts), 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. Every number is a stored post score; nothing is rescored and no comments are loaded.

Posts with at least 10 analyzed comments get flags (posts under 10 are lowSample: true with no flags). meta.flagRules spells out each rule:

  • negative_sentiment: sentiment under 4.5
  • below_baseline / above_baseline: sentiment 1.5+ below / above the baseline
  • commenters_arguing: 25%+ of comments in the debating or fighting consensus bands — commenters arguing with each other, whatever they think of the post
  • off_topic: relevance under 4.5
  • content_topic_gap: content and topic scores 2+ points apart
  • high_engagement_negative: engagement rate in the selection’s top quarter while sentiment is under 4.5

Flags say where to look; POST /analyses on those posts says why. flags in the body keeps only posts with any of the listed flags. engagement.engagementRate is the stored rate, or (likes + comments + shares + saves) / views when none is stored.

JSON pages with limit / cursor (each page re-resolves the selection). format=csv returns every row in one call.

Rate class posts_scan (20 / minute, 500 / day per key).

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

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

sortstring or objectOptional

A field name, or { by, order }. Default postedAt descending; other fields default ascending (worst first for scores).

flagslist of enumsOptional
Keep only posts with any of these flags.
limitintegerOptional1-100Defaults to 25
cursorstringOptional
formatenumOptionalDefaults to json
Allowed values:

Response

Scan rows (JSON, paged) or every row as CSV

datalist of objectsOptional
metaobjectOptional

Errors

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