> ## 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.

# Create a scan

> Submit content to Sapient and get a per-second brain-response scan back.

Submit a piece of content (a video, audio track, or page URL) and Sapient runs it through the brain model, returning a `queued` scan you [poll](/api-reference/get-scan) (or receive on a `webhook_url`). The completed scan is a **per-second timeline**: every lens you ask for, scored second by second, with optional per-second [raw brain-network values](/api-reference/get-scan), benchmarks, reasons, and detected moments.

<Note>
  Mary is temporarily unavailable — all scans run on Qualia, the default model.
</Note>

<Note>
  Videos are capped at **3 minutes**. A longer clip is rejected up front (no GPU spend, no charge); trim or split it before submitting.
</Note>

Pick the [lenses](/api-reference/lenses) you care about; the [`model`](/api-reference/models) runs on Qualia by default. Completed Qualia scans cost **\$2.50** each (see [pricing](/api-reference/pricing)).

## Body Parameters

<ParamField body="input" type="object" required>
  The content to analyze.

  <Expandable title="input">
    <ParamField body="type" type="string" required>
      `video`, `audio`, or `url` — you provide an asset URL. Qualia does not take text input.
    </ParamField>

    <ParamField body="url" type="string">
      A public asset URL, used when `type` is `url` (also accepted as a fallback for `video` / `audio`).
    </ParamField>

    <ParamField body="video_url" type="string">
      The public video URL, used when `type` is `video`.
    </ParamField>

    <ParamField body="audio_url" type="string">
      The public audio URL, used when `type` is `audio`.
    </ParamField>

    <ParamField body="text" type="string">
      Text input is not supported — Qualia takes a video or audio URL.
    </ParamField>

    <ParamField body="modality" type="string">
      Optional hint when `type` is `url`: `video` (default), `audio`, or `image`.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="model" type="string" default="qualia">
  Mary is temporarily unavailable — all scans run on Qualia, the default model (**\$2.50**/scan). It requires a video (or audio) URL input. See [Models](/api-reference/models).
</ParamField>

<ParamField body="lenses" type="string[]" default="[&#x22;attention&#x22;,&#x22;purchase_intent&#x22;,&#x22;manipulation&#x22;]">
  Which [lenses](/api-reference/lenses) to score. Any subset of the four: `attention`, `memory`, `purchase_intent`, `manipulation`. Defaults to the top three. Unknown values are ignored.
</ParamField>

<ParamField body="granularity" type="string" default="second">
  The timeline resolution. Per-second is the default and the only resolution today.
</ParamField>

<ParamField body="options" type="object">
  Toggles for what the completed scan includes.

  <Expandable title="options">
    <ParamField body="include_reasons" type="boolean" default="true">
      Plain-language "why this number" for each lens at each second, plus detected `moments` and a `summary`.
    </ParamField>

    <ParamField body="include_benchmark" type="boolean" default="true">
      A `{ percentile, label }` for each lens at each second, scored against Sapient's corpus.
    </ParamField>

    <ParamField body="include_raw" type="boolean" default="false">
      The underlying per-second values for all seven brain networks (`Visual`, `Somatomotor`, `Dorsal Attention`, `Ventral Attention`, `Limbic`, `Frontoparietal`, `Default Mode`). See [Raw brain networks](/api-reference/get-scan).
    </ParamField>

    <ParamField body="include_fmri" type="boolean" default="false">
      A signed URL to the rendered fMRI artifact, when available.
    </ParamField>
  </Expandable>
</ParamField>

<ParamField body="webhook_url" type="string">
  If set, Sapient `POST`s the completed scan to this URL once it finishes. Best-effort; polling is always available as a fallback.
</ParamField>

## Response

<ResponseField name="scan_id" type="string">
  The scan identifier, e.g. `mary_run_mq7c8f31_jad6o8tl`. Use it to [poll for the result](/api-reference/get-scan).
</ResponseField>

<ResponseField name="status" type="string">
  `queued` on submit. Later transitions to `processing`, then `complete` (or `error`).
</ResponseField>

<ResponseField name="lenses" type="string[]">
  The normalized lens list this scan will score. It echoes your request, deduped and defaulted.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  curl https://www.thesapientcompany.com/api/v1/scans \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
    -H "Content-Type: application/json" \
    -d '{
      "input": { "type": "video", "video_url": "https://yourcdn.com/ad.mp4" },
      "model": "qualia",
      "lenses": ["attention", "purchase_intent", "manipulation"],
      "granularity": "second",
      "options": {
        "include_reasons": true,
        "include_benchmark": true,
        "include_raw": true,
        "include_fmri": false
      },
      "webhook_url": "https://yourapp.com/hooks/sapient"
    }'
  ```

  ```javascript Node theme={null}
  const res = await fetch("https://www.thesapientcompany.com/api/v1/scans", {
    method: "POST",
    headers: {
      Authorization: "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      input: { type: "video", video_url: "https://yourcdn.com/ad.mp4" },
      model: "qualia",
      lenses: ["attention", "purchase_intent", "manipulation"],
      options: { include_raw: true },
      webhook_url: "https://yourapp.com/hooks/sapient",
    }),
  });

  const { scan_id } = await res.json();
  ```

  ```python Python theme={null}
  import requests

  res = requests.post(
      "https://www.thesapientcompany.com/api/v1/scans",
      headers={
          "Authorization": "Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx",
          "Content-Type": "application/json",
      },
      json={
          "input": {"type": "video", "video_url": "https://yourcdn.com/ad.mp4"},
          "model": "qualia",
          "lenses": ["attention", "purchase_intent", "manipulation"],
          "options": {"include_raw": True},
          "webhook_url": "https://yourapp.com/hooks/sapient",
      },
  )

  scan_id = res.json()["scan_id"]
  ```
</RequestExample>

<ResponseExample>
  ```json Queued theme={null}
  {
    "scan_id": "mary_run_mq7c8f31_jad6o8tl",
    "status": "queued",
    "lenses": ["attention", "purchase_intent", "manipulation"]
  }
  ```
</ResponseExample>