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

# Intelligence

> Your org's accumulated cross-scan patterns and semantic recall.

Every completed scan is stored to your org's long-term memory. **Intelligence** rolls that history up into cross-scan patterns: your own per-lens averages, the average per-second curve for each lens, and the seconds where your content repeatedly drops. Add a `q=` query and it also runs **semantic recall** across your stored scans, returning the most relevant moments.

Everything here is strictly org-isolated: the rollup reads only your org's scans, and recall searches only your org's memory.

## Query Parameters

<ParamField query="q" type="string">
  A natural-language query. When present, the response includes a `recall` array of the most semantically relevant stored moments. Omit it for just the rollup.
</ParamField>

## Response

<ResponseField name="scan_count" type="number">
  How many completed scans are in your org's memory.
</ResponseField>

<ResponseField name="lens_averages" type="object">
  Your org's own benchmark: the average `0–100` score per lens across all your scans.
</ResponseField>

<ResponseField name="avg_lens_curves" type="object">
  For each lens, the average score at each second across your scans: your typical per-second shape.
</ResponseField>

<ResponseField name="recurring_drop_seconds" type="object[]">
  The seconds where your content repeatedly weakens, ranked by how often. Each entry is `{ second, lens, count }`.
</ResponseField>

<ResponseField name="query" type="string">
  Echoes `q` when supplied.
</ResponseField>

<ResponseField name="recall" type="object[]">
  Present when `q` is supplied. The most relevant stored moments.

  <Expandable title="recall[]">
    <ResponseField name="scan_id" type="string">Which scan the moment came from.</ResponseField>
    <ResponseField name="kind" type="string">The memory kind, e.g. `moment`.</ResponseField>
    <ResponseField name="lens" type="string">The lens the moment is about.</ResponseField>
    <ResponseField name="second" type="number">The second it occurred.</ResponseField>
    <ResponseField name="text" type="string">The moment's explanation.</ResponseField>
    <ResponseField name="score" type="number">Semantic relevance to `q` (higher is closer).</ResponseField>
    <ResponseField name="created_at" type="string">ISO 8601 timestamp.</ResponseField>
  </Expandable>
</ResponseField>

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

  ```bash With recall theme={null}
  curl "https://www.thesapientcompany.com/api/v1/intelligence?q=attention" \
    -H "Authorization: Bearer sk_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"
  ```
</RequestExample>

<ResponseExample>
  ```json Intelligence (trimmed) theme={null}
  {
    "scan_count": 4,
    "lens_averages": { "attention": 67, "purchase_intent": 60, "manipulation": 48 },
    "avg_lens_curves": {
      "attention": [76, 76, 76, 76, 76, 76, 75, 75, 75, 74 /* … one value per second */],
      "purchase_intent": [63, 63, 63, 63, 62, 63, 63, 63, 63, 63 /* … */],
      "manipulation": [52, 52, 52, 52, 52, 51, 51, 52, 51, 51 /* … */]
    },
    "recurring_drop_seconds": [
      { "second": 58, "lens": "attention", "count": 4 },
      { "second": 5, "lens": "manipulation", "count": 3 },
      { "second": 12, "lens": "purchase_intent", "count": 2 }
      // … ranked by count
    ],
    "query": "attention",
    "recall": [
      {
        "scan_id": "mary_run_mq7ahu4h_bbihywp3",
        "kind": "moment",
        "lens": "attention",
        "second": 56,
        "text": "Attention slipped here (59) as the clip wound down.",
        "score": 0.3056,
        "created_at": "2026-06-09T23:50:57.599Z"
      }
      // … up to 8 hits
    ]
  }
  ```
</ResponseExample>