---
title: "Unified entity timeline (Pro+): one dated, most-recent-first stream interleaving score movements, drift events, lifecycle transitions, X (social) inflection + amplification, Claim Truth transitions + narrative divergence, and captured AI-engine responses + Decision Survival runs. Each event carries an optional `evidence` panel — response excerpts, verified/observed facts, and deep-dive links. A projection over readers the platform already writes; introduces no new collection. Feature-flagged (entity-timeline) — 404 when disabled."
method: GET
path: "/entities/{entityId}/timeline"
tags: ["Layer 2 — Insight"]
---

# Unified entity timeline (Pro+): one dated, most-recent-first stream interleaving score movements, drift events, lifecycle transitions, X (social) inflection + amplification, Claim Truth transitions + narrative divergence, and captured AI-engine responses + Decision Survival runs. Each event carries an optional \`evidence\` panel — response excerpts, verified/observed facts, and deep-dive links. A projection over readers the platform already writes; introduces no new collection. Feature-flagged (entity-timeline) — 404 when disabled.

`GET /entities/{entityId}/timeline`

## Request

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

## Path parameters

- `entityId` string, required

## Query parameters

- `days` integer
- `limit` integer

## Response `200`

OK

- object
  - `data` EntityTimeline: Unified chronological timeline — one dated, most-recent-first stream interleaving score movements, drift events, lifecycle transitions, X (social) inflection/amplification, Claim Truth transitions + narrative divergence, and captured AI-engine responses + Decision Survival runs. Every event carries an optional `evidence` panel the UI reveals on click.
    - `events` TimelineEvent[], required
      - `id` string, required: Stable, deterministic id.
      - `at` string, date-time, required
      - `kind` 'score' | 'drift' | 'lifecycle' | 'x' | 'truthGap' | 'response' | 'googleAi', required: Event class. `x` = X (social) inflection or amplification event; `truthGap` = Claim Truth transition or narrative divergence (Amendment 20); `response` = captured AI-engine responses or a Decision Survival run.
      - `title` string, required
      - `detail` string, required
      - `tone` 'positive' | 'negative' | 'risk' | 'neutral', required
      - `dimension` string: Score dimension (score events only).
      - `magnitude` number: Signed delta magnitude (score events).
      - `severity` string: Drift severity, or `high` for early-warning X spikes / pile-on.
      - `evidence` TimelineEvidence: Optional expandable evidence panel — response excerpts, verified/observed fact rows, deep-dive links, or a supporting narrative note. The UI reveals this on click.
        - `responses` TimelineResponseExcerpt[]
          - `engine` string, required: Engine id — chatgpt / claude / gemini / perplexity / grok.
          - `label` string, required: Public engine label (§7 casing).
          - `text` string, required: Truncated response text (≤ ~500 chars).
          - `at` string, date-time, required
          - `mentionedEntity` boolean
        - `facts` TimelineFactRow[]
          - `label` string, required
          - `value` string, required
        - `links` object[]
          - `label` string, required
          - `href` string, required
        - `note` string: Free-form supporting text (e.g. X narrative context).
    - `windowDays` integer, required
    - `generatedAt` string, date-time, required
    - `counts` object, required
      - `score` integer, required
      - `drift` integer, required
      - `lifecycle` integer, required
      - `x` integer, required
      - `truthGap` integer, required
      - `response` integer, required
      - `googleAi` integer, required
  - `meta` ResponseMeta
    - `requestId` string, required
    - `timestamp` string, date-time, required
    - `apiVersion` string, required
    - `pagination` object
      - `cursor` string, nullable
      - `hasMore` boolean
      - `limit` integer
    - `rateLimit` object
      - `limit` integer
      - `remaining` integer
      - `resetAt` string, date-time
    - `billing` object
      - `creditsUsed` integer
      - `creditsRemaining` integer, nullable
      - `tier` 'free' | 'layer_0_discovery' | 'layer_1_profile' | 'layer_2_insight' | 'layer_3_drift' | 'layer_4_cohort'
      - `allowedLayers` integer[]: Cumulative layer ladder unlocked by this key (0=discovery … 4=cohort). free → []; layer_2_insight → [0,1,2].
      - `mode` 'demo' | 'free' | 'payg' | 'keyed': How the caller is billed: demo (feedback-loop key), free (monthly allowance), payg (Developer PAYG), keyed (paid subscription).
  - `errors` ApiError[]
    - `code` 'ENTITY_NOT_RESOLVED' | 'ENTITY_NOT_FOUND' | 'INVALID_PARAMETER' | 'RATE_LIMITED' | 'INSUFFICIENT_CREDITS' | 'TIER_NOT_AVAILABLE' | 'UNAUTHENTICATED' | 'FORBIDDEN' | 'INTERNAL_ERROR', required
    - `message` string, required
    - `field` string
    - `candidates` object[]

## Other responses

- `404`: Entity or resource not found.

---

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