Guides

The content object

records returns a content array of ranked items. Each item carries the source metadata (platform, title, tags, engagement counts, publishedAt, creatorId, …) plus a set of normalized signals and a single ranking score the list is sorted by.

Every signal is normalized within the result set for that query — values are relative to the other items returned, not absolute.

Signal reference

FieldWhat it isFormula
rawSimilarityRaw vector-store certainty for the best-matching media vector (text→visual).cosine/certainty, pre-normalization. 0 = no multimodal evidence (e.g. a tag-widened row).
similarityrawSimilarity rescaled to ~[0,1] against fixed anchors. A multimodal sub-score — not the overall ranking signal.fixed-anchor rescale of rawSimilarity
textRerankScoreText→text relevance of the query vs the item’s title/description/tags, in [0,1]. null when the row has no usable text.reranker score
relevanceThe combined relevance actually used to rank: similarity blended with textRerankScore, after a soft certainty floor. Prefer this over similarity.(1 − w)·similarity + w·textRerankScore, then ×0.5 if rawSimilarity is below the certainty floor (w is adaptive)
engagementScoreLog-scaled, weighted engagement, normalized to the top item.log1p(views + 2·likes + 3·comments + 4·shares) / max
authorReachNormalized follower count (log-scaled).log1p(followers) / max(log1p(followers))
recencyScoreHow recent vs the oldest/newest item in the set; 0.5 if no date.(ts − oldest) / (newest − oldest)
engagementDepthLike-per-view ratio — engagement quality, not volume.views>0 ? min(1, likes/(views+1)) : 0
rrfScoreReciprocal Rank Fusion across the per-vector result sets (a retrieval-stage signal).Σ 1/(rank + 60) over each vector the item matched
subjectMatchWhether the item matched the query’s subject (vs. a looser tag-widened match).boolean
exampleRankingScoreThe single score the list is sorted by (descending).see below ↓

Ranking — exampleRankingScore

The ranking score branches on engagement coverage — the fraction of items in the set with views > 0 — so sorting stays reliable even on sparse social data.

Sufficient engagement data (coverage ≥ 0.3):

0.60·relevance
  + 0.20·(relevance · engagementScore)
  + 0.08·recencyScore
  + 0.07·authorReach
  + 0.05·engagementDepth

Engagement is gated behind relevance (the relevance · engagementScore product), so an irrelevant viral clip can’t leapfrog on engagement alone.

Sparse engagement data (coverage < 0.3):

0.85·relevance + 0.15·recencyScore

The content list is returned sorted by exampleRankingScore descending.

Weights are tuned as the ranking model evolves — treat the exact coefficients as current behavior, not a fixed contract.

Enrichment

Each item also carries an optional enrichment object — LLM-derived content attributes used for analysis and filtering: themes, aestheticStyle, emotionMood, brandProducts, tone (+ toneConfidence), noveltyScore, saturationScore, and a coverage flag set (attributes / novelty / sentiment) marking which attributes were computed. Fields are null when an attribute wasn’t available for that item.

Relationship graph edges

records also returns a graph over the result set (see the API Reference). Two content nodes are linked by:

  • semantic_similarity — when the cosine similarity of their media vectors is ≥ 0.84.
  • tag_overlap — otherwise, when the Jaccard overlap of their tags is ≥ 0.28.

Plus creator_posted, tagged_with and contains edges connecting creators, tags and narratives.