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

# Scans and Enrichment

> Starter vs deep scans, the async run lifecycle, and what the ideas-json export contains.

## Scan types

|                  | `scanType: "starter"`                      | `scanType: "deep"`                                              |
| ---------------- | ------------------------------------------ | --------------------------------------------------------------- |
| Cost             | No charge (Starter scan allowance)         | Consumes paid account quota                                     |
| Depth            | Core viability analysis + score            | 15+ sections, pivots, citations, full research                  |
| Typical duration | 1-3 min                                    | 5-10 min                                                        |
| Export           | Summary contract                           | Summary + `details.sections`, `details.pivots`, module payloads |
| Modules          | Not available (`403 MODULES_REQUIRE_DEEP`) | Opt-in via [enrich](/modules)                                   |

`scanType` is always explicit - there is no default. A refused deep scan is never silently downgraded to starter; it fails loudly (`402 INSUFFICIENT_TOKENS` or a service-disabled error).

<Note>
  While a deep run is still `PROCESSING`, `analysisTier` reads `basic` until the deep sections land.
  Use `scanType` (your request) as the in-flight signal and `analysisTier` as "is the deep result
  ready yet".
</Note>

## Run lifecycle

```text theme={null}
POST /analyses            -> { id, status: PROCESSING }
GET  /analyses/:id        -> PROCESSING ... COMPLETED (or FAILED)
POST /analyses/:id/enrich -> generates missing export sections (idempotent)
GET  /analyses/:id/export -> ideas-json
```

`readyForExport` is separate from `status`: a run can be `COMPLETED` but still need enrichment before export. Starter runs need Quick Take; deep runs need Quick Take, section briefings, Skeptic's View, and both deferred Action Plan variants (`building`, `hasUsers`). The enrich route skips whatever already exists, so calling it twice never regenerates or double-spends.

Partial enrichment failures return HTTP `207` with a success-shaped body and a `failures` list - retry by calling enrich again.

## The ideas-json export (schemaVersion 2)

Every tier gets the summary contract:

* `verdict`, `score`, `risk`, `quote`, `evidence`
* `details.market` (TAM/SAM/SOM), `details.competitors`, `details.swot`, `details.risks`, `details.validation`
* `details.quickTake`, `details.actionPlanVariants`, `details.citations` (deduped `{ title, url }`)

Deep runs additionally get:

* `details.sections` - business model (+ scenario B), execution fit, go-to-market, lean canvas, Porter forces, VC scorecard, PMF signals, financial projections, synthesis (with pivot recommendation), consistency review, section briefings, Skeptic's View
* `details.pivots` - `{ suggestions, generatedAt }`
* `details.communityDemand`
* `details.founderFit`, `details.playbook`, `details.proofOfDemand` - once the [modules](/modules) have been generated

On starter runs all deep-only fields are `null`. Exports are deterministic: the same run state always serializes identically.

## Batches

`POST /api/agent/analysis-batches` accepts up to 10 items, each with its own `clientRunId` and `scanType` (mix starter and deep intentionally). The batch export includes only completed, export-ready items, plus `omittedItems` explaining every skipped item and aggregate `counts.exported` / `counts.omitted`.