> ## Documentation Index
> Fetch the complete documentation index at: https://api.thesapientcompany.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get a scan

> Poll a scan by id and read the full per-second brain-response timeline.

Poll a scan by its `scan_id` until `status` is `complete`. While in flight the response is just `{ scan_id, status }`. When complete you get the **rich shape**: a per-second `timeline` of lens scores (the headline capability), plus the detected `moments`, the **`buy_moments`** (where buy intent peaks under the Buy / Not Buy lens), a written `summary`, and, depending on the [options](/api-reference/create-scan#param-options) the scan was created with, per-second `benchmark`, `reasons`, `raw` brain-network values, and an `fmri_url`.

A scan that isn't your org's, or doesn't exist, returns `404`. The first time you fetch a completed scan, the [model](/api-reference/models) charge settles (\$2.50 for Qualia, the default and only available model; Mary is temporarily unavailable) and the result is stored to your org's [intelligence](/api-reference/intelligence).

## Path Parameters

<ParamField path="id" type="string" required>
  The scan identifier returned by [Create a scan](/api-reference/create-scan), e.g. `qualia_run_mq7aht79_hrac1kka`.
</ParamField>

## In-flight response

<ResponseField name="scan_id" type="string">The scan identifier.</ResponseField>

<ResponseField name="status" type="string">
  `queued`, `processing`, `complete`, `error`, or `cancelled`. When `error`/`cancelled`, an `error` string is included.
</ResponseField>

## Completed response

<ResponseField name="scan_id" type="string">The scan identifier.</ResponseField>

<ResponseField name="status" type="string">`complete`.</ResponseField>

<ResponseField name="overall_score" type="number">
  The headline `0–100` brain-engagement score for the whole clip, the single number to lead with. This is a **directional average** over the clip (not a measured ground truth), and it's the same value the dashboard and result email report. May be `null` for a clip the model couldn't score.
</ResponseField>

<ResponseField name="grade" type="string">
  The letter grade for `overall_score` (e.g. `B`, `C`, `D`, `E`). When the model didn't emit its own grade, it's derived from `overall_score` using the standard bands: `≥75` is B, `≥60` is C, `≥45` is D, and anything below that is E.
</ResponseField>

<ResponseField name="duration_sec" type="number">
  The clip length in seconds. It equals the number of entries in `timeline`.
</ResponseField>

<ResponseField name="lenses" type="string[]">
  The [lenses](/api-reference/lenses) scored on this scan, in order.
</ResponseField>

<ResponseField name="timeline" type="object[]">
  **The per-second breakout**, one entry per second of the clip. This is the core of the result: every lens, scored at every second, so you can see exactly where a piece holds and where it slips.

  <Expandable title="timeline[]">
    <ResponseField name="second" type="number">
      Zero-based second index (`0` is the first second).
    </ResponseField>

    <ResponseField name="scores" type="object">
      Each requested lens scored `0–100` at this second (`50` = neutral). Keyed by public lens name, e.g. `{ "attention": 76, "purchase_intent": 63, "manipulation": 51 }`.
    </ResponseField>

    <ResponseField name="benchmark" type="object">
      Present when the scan was created with `include_benchmark` (default). For each lens, where this second's score falls in Sapient's corpus: `{ percentile, label }`. Labels are `well above average` (≥90), `above average` (≥70), `average` (≥40), `below average` (≥20), `well below average` (under 20).
    </ResponseField>

    <ResponseField name="reasons" type="object">
      Present when the scan was created with `include_reasons` (default). A plain-language "why this number" string per lens, grounded in the brain read.
    </ResponseField>

    <ResponseField name="raw" type="object">
      Present when the scan was created with `include_raw`. The underlying **per-second value for each of the seven brain networks**, the rawest signal the model produces: `Visual`, `Somatomotor`, `Dorsal Attention`, `Ventral Attention`, `Limbic`, `Frontoparietal`, `Default Mode`. Every lens score is derived from these. See [the 7 networks](/knowledge-base/the-7-networks).
    </ResponseField>

    <ResponseField name="raw_labeled" type="object">
      Present alongside `raw` when `include_raw` is set. The **same per-second network values**, re-keyed to Sapient's plain-language vocabulary so you don't have to know the neuroscience names. The mapping is:

      | Network (in `raw`)  | Label (in `raw_labeled`) |
      | ------------------- | ------------------------ |
      | `Visual`            | `Visual`                 |
      | `Somatomotor`       | `Voice`                  |
      | `Frontoparietal`    | `Cognitive`              |
      | `Limbic`            | `Emotional`              |
      | `Default Mode`      | `Memory`                 |
      | `Dorsal Attention`  | `Attention`              |
      | `Ventral Attention` | `Salience`               |

      `raw` is unchanged and back-compatible; `raw_labeled` is purely additive.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="moments" type="object[]">
  The notable second-to-second shifts the model flagged: peaks and drops worth a human's attention. Present when `include_reasons`.

  <Expandable title="moments[]">
    <ResponseField name="type" type="string">
      `attention_drop`, `attention_peak`, `lens_drop`, or `lens_peak`.
    </ResponseField>

    <ResponseField name="lens" type="string">The lens this moment is about.</ResponseField>
    <ResponseField name="second" type="number">The second it occurred.</ResponseField>
    <ResponseField name="from" type="number">The lens score the second before.</ResponseField>
    <ResponseField name="to" type="number">The lens score at this second.</ResponseField>
    <ResponseField name="delta" type="number">The change (`to − from`).</ResponseField>
    <ResponseField name="z" type="number">How big the shift is relative to the clip's own variation.</ResponseField>

    <ResponseField name="reason" type="string">
      Why it matters: the brain read, joined with the on-screen or audio line when one was detected.
    </ResponseField>

    <ResponseField name="brainReason" type="string">The brain-only explanation.</ResponseField>

    <ResponseField name="contentLine" type="string">
      The transcript / on-screen line at that second, or `null` if none was matched.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="summary" type="string">
  A short written read of the whole clip: the averages and the moments that mattered. Present when `include_reasons`.
</ResponseField>

<ResponseField name="buy_moments" type="object[]">
  The **buy moments** under the Buy / Not Buy lens — the windows where predicted purchase intent (reward minus hesitation, the same basis as the `purchase_intent` lens) holds above the clip's average. Each is where you'd place a CTA or the offer. Present when `include_reasons`; `null` when no window clears the bar (or the scan has no per-second network data).

  <Expandable title="buy_moments[]">
    <ResponseField name="start_sec" type="number">First second of the buy-moment window.</ResponseField>
    <ResponseField name="end_sec" type="number">Last second of the window.</ResponseField>
    <ResponseField name="peak_sec" type="number">The single strongest second within the window.</ResponseField>

    <ResponseField name="strength" type="string">
      Plain-language rank within the clip, e.g. `Strongest buy moment`, `2nd-strongest buy moment`.
    </ResponseField>

    <ResponseField name="strength_pct" type="number">
      Relative strength 0–100 (this window's peak vs the clip's strongest).
    </ResponseField>

    <ResponseField name="quote" type="string">
      What is said at the peak second (from the transcript), or `null` when there's no speech there.
    </ResponseField>

    <ResponseField name="insight" type="string">
      A plain-language read of why this beat drives buying (the persuasion takeaway).
    </ResponseField>

    <ResponseField name="trigger" type="string">
      What in the predicted response flagged this second — the driver mix (reward / personal-relevance / a drop in skepticism).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="manipulation" type="object">
  The full **Manipulation read** — present only when the `manipulation` lens was scored on this scan. It's the same research-grounded block the [Manipulation lens](/knowledge-base/lenses/manipulation) renders in the dashboard, and the **identical shape** returned inline by `POST /v1/analyze` under `result.manipulation`. Every number is **directional and network-proxied** (Yeo-7 networks standing in for the paper ROIs), not a vertex-level fMRI claim.

  <Expandable title="manipulation">
    <ResponseField name="conversion_risk" type="number">
      `0–100`. How hard the content can move belief past the viewer's critical guard. Higher = more persuasive override.
    </ResponseField>

    <ResponseField name="risk_band" type="string">
      `low`, `moderate`, `elevated`, or `high` — the band for `conversion_risk`.
    </ResponseField>

    <ResponseField name="cognitive_sovereignty_index" type="number">
      The signed **Cognitive Sovereignty Index** (CSI). Negative = independent judgment is being suppressed; positive = it stays intact.
    </ResponseField>

    <ResponseField name="sovereignty" type="number">
      `0–100`. How much independent judgment is preserved (higher = safer). The inverse of `conversion_risk`.
    </ResponseField>

    <ResponseField name="pbi" type="number">
      The **Prefrontal Balance Index** (vmPFC − dlPFC). Higher = more reward/emotion-driven relative to deliberate reasoning.
    </ResponseField>

    <ResponseField name="threat" type="object">
      The headline threat verdict shown in the UI banner: `{ label, severity, color, note }`, where `severity` is one of `critical`, `high`, `moderate`, or `nominal`.
    </ResponseField>

    <ResponseField name="population" type="object">
      A **directional** population-impact projection — `{ per_ten, per_ten_thousand, note }`. This is a model estimate (projected from the suppression profile), **not a measured outcome**.
    </ResponseField>

    <ResponseField name="quadrant" type="object">
      Where the content lands on the two-axis manipulation map: `{ key, label, lowers_guard, wins_over, how }`. `key` is `clean`, `coercive`, `seductive`, or `total`; `lowers_guard` and `wins_over` are the two `0–100` axes.
    </ResponseField>

    <ResponseField name="circuits" type="object[]">
      The four brain systems that drive the read, each `{ key, label, plain, value, direction, reading, meaning }` — critical thinking, reward & approval, gut-instinct alarm, and personal relevance.
    </ResponseField>

    <ResponseField name="mechanisms" type="object[]">
      The persuasion-mechanism split (sums to 1), each `{ key, label, share }`: Social Reward (`SR`), Motivational Rapport (`MR`), Coercive Authority (`CA`).
    </ResponseField>

    <ResponseField name="timeline" type="object[]">
      The per-second **guard-down timeline**, each `{ sec, exposure, reward, effort, alarm }` where `exposure = reward − effort − alarm`. The seconds with the highest `exposure` are where the viewer is most open to the message.
    </ResponseField>

    <ResponseField name="peak_moment" type="object">
      The single most-persuasive window, or `null`: `{ peak_sec, start_sec, end_sec, quote, why }`.
    </ResponseField>

    <ResponseField name="tactics" type="object[]">
      The persuasion tactics detected in the transcript, each `{ tactic, kind, at_sec, quote }` (Cialdini / PMTT families, anchored to the second they appear).
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="fmri_url" type="string">
  A signed (1-hour) URL to the rendered fMRI artifact, or `null`. Present only when the scan was created with `include_fmri`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://www.thesapientcompany.com/api/v1/scans/qualia_run_mq7aht79_hrac1kka \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</RequestExample>

<ResponseExample>
  ```json Completed (trimmed) theme={null}
  {
    "scan_id": "qualia_run_mq7aht79_hrac1kka",
    "status": "complete",
    "overall_score": 68,
    "grade": "C",
    "duration_sec": 60,
    "lenses": ["attention", "purchase_intent", "manipulation"],
    "timeline": [
      {
        "second": 11,
        "scores": { "attention": 74, "purchase_intent": 62, "manipulation": 51 },
        "benchmark": {
          "attention": { "percentile": 100, "label": "well above average" },
          "purchase_intent": { "percentile": 100, "label": "well above average" },
          "manipulation": { "percentile": 92.8, "label": "well above average" }
        },
        "reasons": {
          "attention": "Attention climbed here (74); the viewer is locked in.",
          "purchase_intent": "The pull toward buying strengthened here (62).",
          "manipulation": "It leaned a little harder on emotional persuasion here (51)."
        }
      }
      // … 60 entries total, one per second
    ],
    "moments": [
      {
        "type": "lens_drop",
        "lens": "manipulation",
        "second": 5,
        "from": 52,
        "to": 51,
        "delta": -1,
        "z": 1.6,
        "reason": "Manipulation eased off slightly here (51); the viewer is thinking it through.",
        "brainReason": "Manipulation eased off slightly here (51); the viewer is thinking it through.",
        "contentLine": null
      },
      {
        "type": "attention_peak",
        "lens": "attention",
        "second": 59,
        "from": 57,
        "to": 59,
        "delta": 2,
        "z": 1.5,
        "reason": "Attention climbed back up here (59) right before the end.",
        "brainReason": "Attention climbed back up here (59) right before the end.",
        "contentLine": null
      }
      // … 9 moments total
    ],
    "summary": "Across the clip, attention averaged a solid 68, the pull toward buying sat at 60, and manipulation stayed in the middle range at 48. By 0:11 the clip hit its strongest stretch: attention peaked at 74 and buy-intent rose with it. Attention then slipped late, around 0:56 and 0:58, before climbing back up at 0:59 right at the close.",
    "buy_moments": [
      {
        "start_sec": 31,
        "end_sec": 36,
        "peak_sec": 36,
        "strength": "Strongest buy moment",
        "strength_pct": 100,
        "quote": "it generates a highly detailed plan that allows it to test each",
        "insight": "Lands as personally relevant — it reads like it's about them, with zero skepticism.",
        "trigger": "Flagged because the 'I want this' response and the 'this is for me' response both spiked, while skepticism dropped away."
      }
    ]
  }
  ```

  ```json With include_raw (per-second brain networks) theme={null}
  {
    "scan_id": "qualia_run_mq7c8f31_jad6o8tl",
    "status": "complete",
    "overall_score": 71,
    "grade": "C",
    "duration_sec": 5,
    "lenses": ["attention", "purchase_intent", "manipulation"],
    "timeline": [
      {
        "second": 0,
        "scores": { "attention": 65, "purchase_intent": 61, "manipulation": 48 },
        "raw": {
          "Visual": 0.153656,
          "Somatomotor": 0.155845,
          "Dorsal Attention": 0.153762,
          "Ventral Attention": 0.159269,
          "Limbic": 0.168229,
          "Frontoparietal": 0.166151,
          "Default Mode": 0.161048
        },
        "raw_labeled": {
          "Visual": 0.153656,
          "Voice": 0.155845,
          "Attention": 0.153762,
          "Salience": 0.159269,
          "Emotional": 0.168229,
          "Cognitive": 0.166151,
          "Memory": 0.161048
        },
        "benchmark": {
          "attention": { "percentile": 79.9, "label": "above average" },
          "purchase_intent": { "percentile": 99.75, "label": "well above average" },
          "manipulation": { "percentile": 33.6, "label": "below average" }
        },
        "reasons": {
          "attention": "Attention held steady (65) at the open.",
          "purchase_intent": "Buy-intent held steady (61).",
          "manipulation": "Manipulation held steady (48), near neutral."
        }
      }
      // … one entry per second, each with its own raw network slice
    ],
    "moments": [],
    "summary": "Attention held steady around 65 and the pull toward buying stayed firm near 61, while emotional persuasion sat just below neutral at 48."
  }
  ```

  ```json manipulation block (when the manipulation lens is scored) theme={null}
  {
    "scan_id": "qualia_run_mq7aht79_hrac1kka",
    "status": "complete",
    "lenses": ["attention", "manipulation"],
    "manipulation": {
      "conversion_risk": 72,
      "risk_band": "elevated",
      "cognitive_sovereignty_index": -0.413,
      "sovereignty": 28,
      "pbi": 0.207,
      "threat": {
        "label": "ELEVATED INFLUENCE",
        "severity": "high",
        "color": "#FF6B4A",
        "note": "Strong pull on emotion with partial evaluative override."
      },
      "population": {
        "per_ten": 7,
        "per_ten_thousand": 7000,
        "note": "Projected from the suppression profile — a directional model estimate, not a measured outcome."
      },
      "quadrant": {
        "key": "seductive",
        "label": "Seductive",
        "lowers_guard": 41,
        "wins_over": 63,
        "how": "We watched four brain systems respond second-by-second: reward & approval ran above normal, while critical thinking dropped below normal. Reward on, guard up = it seduces more than it pressures."
      },
      "circuits": [
        {
          "key": "reward",
          "label": "Reward & approval",
          "plain": "the part that lights up when something feels good or rewarding",
          "value": 0.214,
          "direction": "up",
          "reading": "above normal",
          "meaning": "Running hot — the offer feels good before it's judged."
        }
        // … four circuits: critical thinking, reward & approval, gut-instinct alarm, personal relevance
      ],
      "mechanisms": [
        { "key": "SR", "label": "Social Reward", "share": 0.52 },
        { "key": "MR", "label": "Motivational Rapport", "share": 0.31 },
        { "key": "CA", "label": "Coercive Authority", "share": 0.17 }
      ],
      "timeline": [
        { "sec": 0, "exposure": 0.18, "reward": 0.21, "effort": 0.01, "alarm": 0.02 }
        // … one entry per second
      ],
      "peak_moment": {
        "peak_sec": 12,
        "start_sec": 11,
        "end_sec": 13,
        "quote": "this is the one thing nobody is telling you",
        "why": "At this second, the reward response spiked, critical thinking dropped, and the gut-instinct alarm went quiet — so the viewer is at their most open to the message right here."
      },
      "tactics": [
        {
          "tactic": "Scarcity / secrecy",
          "kind": "limited or hidden",
          "at_sec": 12,
          "quote": "this is the one thing nobody is telling you"
        }
      ]
    }
  }
  ```

  ```json In-flight theme={null}
  {
    "scan_id": "qualia_run_mq7aht79_hrac1kka",
    "status": "processing"
  }
  ```
</ResponseExample>