Skip to main content
GET
/
v1
/
scans
/
{id}
curl https://www.thesapientcompany.com/api/v1/scans/mary_run_mq7aht79_hrac1kka \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "scan_id": "mary_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."
}
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, a written summary, and, depending on the 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 per-model charge settles ($0.50 for Mary, $1.00 for Qualia) and the result is stored to your org’s intelligence.

​
Path Parameters

​
id
string
required
The scan identifier returned by Create a scan, e.g. mary_run_mq7aht79_hrac1kka.

​
In-flight response

​
scan_id
string
The scan identifier.
​
status
string
queued, processing, complete, error, or cancelled. When error/cancelled, an error string is included.

​
Completed response

​
scan_id
string
The scan identifier.
​
status
string
complete.
​
overall_score
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.
​
grade
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.
​
duration_sec
number
The clip length in seconds. It equals the number of entries in timeline.
​
lenses
string[]
The lenses scored on this scan, in order.
​
timeline
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.
​
moments
object[]
The notable second-to-second shifts the model flagged: peaks and drops worth a human’s attention. Present when include_reasons.
​
summary
string
A short written read of the whole clip: the averages and the moments that mattered. Present when include_reasons.
​
fmri_url
string
A signed (1-hour) URL to the rendered fMRI artifact, or null. Present only when the scan was created with include_fmri.
curl https://www.thesapientcompany.com/api/v1/scans/mary_run_mq7aht79_hrac1kka \
  -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{
  "scan_id": "mary_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."
}