---
title: "Latest real-time X (social) read for an entity (Pro+) — sentiment, key voices, praises / complaints, expansion graph, timeline, early-warning."
method: GET
path: "/entities/{entityId}/x-sentiment"
tags: ["Layer 2 — Insight"]
---

# Latest real-time X (social) read for an entity (Pro+) — sentiment, key voices, praises / complaints, expansion graph, timeline, early-warning.

`GET /entities/{entityId}/x-sentiment`

## Request

- Base URL: `https://entidex.com/api/v1`
- URL: `https://entidex.com/api/v1/entities/{entityId}/x-sentiment`
- Auth: HTTP bearer

## Path parameters

- `entityId` string, required

## Query parameters

- `history` boolean

## Response `200`

Latest X sentiment read (when ?history is absent or false), or the stored series (when ?history=true). When no read has been collected, returns the standard ok envelope wrapping null.

- union
  - XSentimentSnapshot: Single calibrated X (social surface) read. Public-facing schema name omits the provider mechanic per CANON §7 — internally this maps to the GrokXSentimentResult shape.
    - `entitySlug` string, required
    - `found` boolean, required
    - `sentimentScore` number, required: Weighted polarity, -1..1.
    - `sentimentLabel` 'positive' | 'mostly_positive' | 'neutral' | 'mixed' | 'negative', required
    - `volumeBucket` 'none' | 'low' | 'moderate' | 'high' | 'viral', required: Volume is a lower-bound estimate — never a precise count.
    - `approxMentions` integer, required: Lower-bound approximate mention count — derived for weighting only.
    - `windowHours` integer, required: Look-back window of the read.
    - `keyVoices` XSentimentKeyVoice[], required
      - `handle` string, required: Display with @ prefix.
      - `stance` 'ally' | 'opponent' | 'neutral', required
      - `influence` 'high' | 'medium' | 'low', required: Engagement proxy — NOT a follower count.
      - `cites` integer[], required
    - `topPraises` XSentimentClaim[], required
      - `claim` string, required
      - `cites` integer[], required
    - `topComplaints` XSentimentClaim[], required
      - `claim` string, required
      - `cites` integer[], required
    - `authenticity` XSentimentAuthenticity, required: Heuristic organic-vs-amplified read. Reported as heuristic only — never as definitive bot detection (CANON §7).
      - `assessment` string, required
      - `patterns` string[], required
      - `confidence` 'low' | 'medium', required
    - `narrativeContext` string, required
    - `expansion` XSentimentExpansionLink[], required
      - `name` string, required
      - `kind` 'person' | 'org' | 'product' | 'outlet' | 'account' | 'topic', required
      - `relation` 'host_of' | 'owner_of' | 'founder_of' | 'member_of' | 'affiliated_with' | 'parent_of' | 'subsidiary_of' | 'competitor_of' | 'collaborator_of' | 'related_to', required: 1:1 with the typed entity relationship taxonomy (Amendment 14).
      - `narrative` string, required
      - `linkSentiment` number, required: Joint-narrative sentiment, -1..1.
      - `coMentionStrength` 'weak' | 'notable' | 'dominant', required
      - `cites` integer[], required
    - `timeline` XSentimentTimelineEvent[], required
      - `at` string, date-time, required
      - `event` 'volume_spike' | 'sentiment_shift' | 'key_post_viral' | 'external_trigger' | 'new_claim' | 'notable_post', required
      - `summary` string, required
      - `sentimentAfter` number, nullable
      - `cites` integer[], required
    - `earlyWarning` XSentimentEarlyWarning, required
      - `spikeDetected` boolean, required
      - `note` string, required
    - `sources` XSentimentSource[], required
      - `url` string, required
      - `author` string, required: Handle without the leading "@".
      - `postedAt` string, date-time, required
      - `kind` 'post' | 'reply' | 'quote' | 'unknown'
    - `citations` string[], required
    - `confidence` integer, required
    - `model` string, required: Internal — read-model identifier.
    - `collectedAt` string, date-time, required
    - `grokCoupling` XGrokCoupling: X → Grok coupling read: day-aligned co-movement and level concordance between the observed X conversation about the entity and Grok’s own perception of it, with a lead/lag read when one side clearly moves first. Observational — a coupling read, not a causal claim. `available: false` with reason `insufficient_history` until enough overlapping days accrue.
      - `available` boolean, required
      - `reason` 'insufficient_history': Present when available=false.
      - `coMovement` number: Day-aligned co-movement of the two series.
      - `concordance` number: 100 − mean level gap between the day-aligned series.
      - `lead` object, nullable
        - `leader` 'x' | 'grok'
        - `lagDays` integer
        - `coMovementAtLag` number
      - `sampleDays` integer
      - `windowDays` integer
      - `methodology` string
      - `computedAt` string, date-time
    - `xProfile` XProfileSnapshot, nullable: Official X profile snapshot for the entity’s cross-verified X handle: follower/following/post counts, platform verification state, and bio. Collected at most once per 24h; null while no official-API credential is provisioned.
      - `entitySlug` string
      - `username` string
      - `userId` string
      - `displayName` string
      - `followers` integer
      - `following` integer
      - `postCount` integer
      - `listedCount` integer
      - `verified` boolean
      - `verifiedType` string, nullable
      - `bio` string, nullable
      - `accountCreatedAt` string, date-time, nullable
      - `collectedAt` string, date-time
      - `source` 'x_api'
    - `xNarrative` XNarrativeRead, nullable: Official-API narrative read of the X conversation about the entity: a sampled set of mentions of the entity’s cross-verified X handle, scored for sentiment and intent, with emerging topics and amplification events (viral post, contested post, pile-on, volume surge). Collected at most once per 24h; null while no official-API credential is provisioned.
      - `entitySlug` string
      - `username` string
      - `sampleSize` integer: Number of X posts sampled in the read.
      - `sentimentScore` integer: Mean 0–100 polarity over the sampled posts.
      - `sentimentLabel` 'positive' | 'mixed' | 'negative'
      - `intentDistribution` object: Counts of sampled posts by intent class.
        - `praise` integer
        - `question` integer
        - `complaint` integer
        - `suggestion` integer
        - `neutral` integer
      - `emergingTopics` string[]: Deterministic top topics across the sampled posts.
      - `amplification` XAmplificationEvent[]
        - `kind` 'viral_post' | 'ratio' | 'pile_on' | 'volume_surge', required
        - `summary` string, required
        - `evidencePostId` string, nullable
        - `direction` 'positive' | 'negative', required
        - `confidence` number, required
        - `at` string, date-time, required
      - `postsPerHour` number: Observed density of the X conversation across the sampled window.
      - `windowHours` number: Span of the sampled window in hours.
      - `collectedAt` string, date-time
      - `source` 'x_api'
  - XSentimentSnapshot[]: Append-only series of stored X sentiment reads (oldest first).
    - `entitySlug` string, required
    - `found` boolean, required
    - `sentimentScore` number, required: Weighted polarity, -1..1.
    - `sentimentLabel` 'positive' | 'mostly_positive' | 'neutral' | 'mixed' | 'negative', required
    - `volumeBucket` 'none' | 'low' | 'moderate' | 'high' | 'viral', required: Volume is a lower-bound estimate — never a precise count.
    - `approxMentions` integer, required: Lower-bound approximate mention count — derived for weighting only.
    - `windowHours` integer, required: Look-back window of the read.
    - `keyVoices` XSentimentKeyVoice[], required
      - `handle` string, required: Display with @ prefix.
      - `stance` 'ally' | 'opponent' | 'neutral', required
      - `influence` 'high' | 'medium' | 'low', required: Engagement proxy — NOT a follower count.
      - `cites` integer[], required
    - `topPraises` XSentimentClaim[], required
      - `claim` string, required
      - `cites` integer[], required
    - `topComplaints` XSentimentClaim[], required
      - `claim` string, required
      - `cites` integer[], required
    - `authenticity` XSentimentAuthenticity, required: Heuristic organic-vs-amplified read. Reported as heuristic only — never as definitive bot detection (CANON §7).
      - `assessment` string, required
      - `patterns` string[], required
      - `confidence` 'low' | 'medium', required
    - `narrativeContext` string, required
    - `expansion` XSentimentExpansionLink[], required
      - `name` string, required
      - `kind` 'person' | 'org' | 'product' | 'outlet' | 'account' | 'topic', required
      - `relation` 'host_of' | 'owner_of' | 'founder_of' | 'member_of' | 'affiliated_with' | 'parent_of' | 'subsidiary_of' | 'competitor_of' | 'collaborator_of' | 'related_to', required: 1:1 with the typed entity relationship taxonomy (Amendment 14).
      - `narrative` string, required
      - `linkSentiment` number, required: Joint-narrative sentiment, -1..1.
      - `coMentionStrength` 'weak' | 'notable' | 'dominant', required
      - `cites` integer[], required
    - `timeline` XSentimentTimelineEvent[], required
      - `at` string, date-time, required
      - `event` 'volume_spike' | 'sentiment_shift' | 'key_post_viral' | 'external_trigger' | 'new_claim' | 'notable_post', required
      - `summary` string, required
      - `sentimentAfter` number, nullable
      - `cites` integer[], required
    - `earlyWarning` XSentimentEarlyWarning, required
      - `spikeDetected` boolean, required
      - `note` string, required
    - `sources` XSentimentSource[], required
      - `url` string, required
      - `author` string, required: Handle without the leading "@".
      - `postedAt` string, date-time, required
      - `kind` 'post' | 'reply' | 'quote' | 'unknown'
    - `citations` string[], required
    - `confidence` integer, required
    - `model` string, required: Internal — read-model identifier.
    - `collectedAt` string, date-time, required
    - `grokCoupling` XGrokCoupling: X → Grok coupling read: day-aligned co-movement and level concordance between the observed X conversation about the entity and Grok’s own perception of it, with a lead/lag read when one side clearly moves first. Observational — a coupling read, not a causal claim. `available: false` with reason `insufficient_history` until enough overlapping days accrue.
      - `available` boolean, required
      - `reason` 'insufficient_history': Present when available=false.
      - `coMovement` number: Day-aligned co-movement of the two series.
      - `concordance` number: 100 − mean level gap between the day-aligned series.
      - `lead` object, nullable
        - `leader` 'x' | 'grok'
        - `lagDays` integer
        - `coMovementAtLag` number
      - `sampleDays` integer
      - `windowDays` integer
      - `methodology` string
      - `computedAt` string, date-time
    - `xProfile` XProfileSnapshot, nullable: Official X profile snapshot for the entity’s cross-verified X handle: follower/following/post counts, platform verification state, and bio. Collected at most once per 24h; null while no official-API credential is provisioned.
      - `entitySlug` string
      - `username` string
      - `userId` string
      - `displayName` string
      - `followers` integer
      - `following` integer
      - `postCount` integer
      - `listedCount` integer
      - `verified` boolean
      - `verifiedType` string, nullable
      - `bio` string, nullable
      - `accountCreatedAt` string, date-time, nullable
      - `collectedAt` string, date-time
      - `source` 'x_api'
    - `xNarrative` XNarrativeRead, nullable: Official-API narrative read of the X conversation about the entity: a sampled set of mentions of the entity’s cross-verified X handle, scored for sentiment and intent, with emerging topics and amplification events (viral post, contested post, pile-on, volume surge). Collected at most once per 24h; null while no official-API credential is provisioned.
      - `entitySlug` string
      - `username` string
      - `sampleSize` integer: Number of X posts sampled in the read.
      - `sentimentScore` integer: Mean 0–100 polarity over the sampled posts.
      - `sentimentLabel` 'positive' | 'mixed' | 'negative'
      - `intentDistribution` object: Counts of sampled posts by intent class.
        - `praise` integer
        - `question` integer
        - `complaint` integer
        - `suggestion` integer
        - `neutral` integer
      - `emergingTopics` string[]: Deterministic top topics across the sampled posts.
      - `amplification` XAmplificationEvent[]
        - `kind` 'viral_post' | 'ratio' | 'pile_on' | 'volume_surge', required
        - `summary` string, required
        - `evidencePostId` string, nullable
        - `direction` 'positive' | 'negative', required
        - `confidence` number, required
        - `at` string, date-time, required
      - `postsPerHour` number: Observed density of the X conversation across the sampled window.
      - `windowHours` number: Span of the sampled window in hours.
      - `collectedAt` string, date-time
      - `source` 'x_api'

---

[API](https://skmtc.dev/entidex/apis/entidex-api.md) · [All operations](https://skmtc.dev/entidex/apis/entidex-api/llms.txt) · [OpenAPI document](https://skmtc.dev/entidex/apis/entidex-api/revisions/86b92f21a09a?raw)