> Source: https://vitna.ai/docs/api/v1/engine/pipeline
> Raw Markdown: https://vitna.ai/docs/api/v1/engine/pipeline.md
> Corpus index: https://vitna.ai/llms.txt

# Stateless compound pipeline analysis

Evaluate a multi-stage, multi-class AI pipeline Bill of Materials, per-run trace
attribution, compound reliability, and cross-layer spend optimization in memory
with no API key and zero retention.

```
POST /api/v1/pipeline
```

```bash
curl -X POST https://vitna.ai/api/v1/pipeline \
  -H "content-type: application/json" \
  -d '{
    "name": "Deep research report",
    "runLabel": "reports",
    "monthlyRuns": 10000,
    "discoverPeers": true,
    "stages": [
      {
        "id": "search",
        "classId": "tooling",
        "incumbentSkuId": "tavily/search",
        "invocationsPerRun": 6,
        "unitProfile": { "toolCallsPerUnit": 1 }
      },
      {
        "id": "parse",
        "classId": "extraction",
        "incumbentSkuId": "mistral/ocr",
        "invocationsPerRun": 8,
        "unitProfile": { "ocrPagesPerUnit": 1 }
      },
      {
        "id": "synthesize",
        "classId": "model",
        "incumbentSkuId": "openai/gpt-5.4",
        "invocationsPerRun": 1,
        "unitProfile": { "inputTokensPerUnit": 18000, "outputTokensPerUnit": 2200 },
        "constraints": {
          "qualityFloor": 93.0,
          "economicThresholdPct": 15,
          "requiresCapabilities": ["tools"]
        },
        "candidates": ["anthropic/claude-sonnet-4-6"]
      }
    ],
    "evidence": [
      { "skuId": "openai/gpt-5.4", "measuredAt": "2026-10-22", "metrics": { "successRatePct": 95.0 } },
      { "skuId": "anthropic/claude-sonnet-4-6", "measuredAt": "2026-10-22", "metrics": { "successRatePct": 94.5 } }
    ]
  }'
```

## What is evaluated

Runs [`evaluatePipeline`](../../../routing/pipelines.md) in memory across any of
the 10 Witness component classes (`model`, `compute`, `retrieval`, `speech`,
`tooling`, `extraction`, `translation`, `image`, `video`, `music`), plus optional
inline `privateRates` for self-hosted or custom contract SKUs, `ledgerRows`
(`x-vitna-run` runtime traces), and `evidence`:

1. **Cross-layer Bill of Materials**: computes per-stage and total
   `costPerRunUsd`, `monthlyCostUsd`, `annualCostUsd`, `breakdown.byClass`,
   `breakdown.byProvider`, and `breakdown.provenance` (splitting Witness archive
   prices from inline `privateRates`).
2. **Compound reliability and critical-path latency**: computes
   `compoundSuccessRatePct` and `costPerSuccessfulRunUsd` when every
   critical-path stage carries `successRatePct` evidence, and sums
   `criticalPathLatencyP90Ms`.
3. **Two-tier spend optimization**: separates verified `decisionReadySwitches`
   (cleared by `decide()`) from `exploratoryTests` (eligible lower-cost list
   levers awaiting workload evaluation).

Payloads are never persisted (`Cache-Control: no-store`). Also exposed to MCP
clients as `vitna_analyze_pipeline` on [`POST /api/v1/mcp`](mcp.md).

## Response shape

```json
{
  "pipeline": {
    "id": "inline/pipeline",
    "name": "Deep research report",
    "orgId": null,
    "runLabel": "reports",
    "monthlyRuns": 10000,
    "stageCount": 3,
    "criticalPathStageCount": 3
  },
  "totals": {
    "costPerRunUsd": 0.122,
    "monthlyCostUsd": 1220,
    "annualCostUsd": 14640,
    "pricedStageCount": 3,
    "unpricedStageCount": 0,
    "measuredQualityStageCount": 1,
    "compoundSuccessRatePct": null,
    "strictAllCallsSuccessRatePct": null,
    "costPerSuccessfulRunUsd": null,
    "criticalPathLatencyP90Ms": null,
    "latencyComplete": false
  },
  "breakdown": {
    "byClass": [ ... ],
    "byProvider": [ ... ],
    "provenance": {
      "witnessedRunCostUsd": 0.122,
      "enteredRunCostUsd": 0,
      "witnessedSharePct": 100,
      "enteredSharePct": 0,
      "mixedProvenance": false,
      "pricePeriodIds": [ ... ],
      "enteredPriceIds": []
    }
  },
  "bottlenecks": { ... },
  "optimization": {
    "currentCostPerRunUsd": 0.122,
    "optimizedCostPerRunUsd": 0.122,
    "verifiedRunSavingsUsd": 0,
    "verifiedMonthlySavingsUsd": 0,
    "verifiedAnnualSavingsUsd": 0,
    "verifiedSavingsPct": 0,
    "exploratoryAdditionalRunSavingsUsd": 0.036,
    "exploratoryAdditionalMonthlySavingsUsd": 360,
    "decisionReadySwitches": [],
    "exploratoryTests": [ ... ]
  },
  "stages": [ ... ],
  "runAttribution": null,
  "caveats": [ ... ],
  "recommendedCommands": [ ... ],
  "sentence": "Pipeline Deep research report costs $0.122000 per report ($1220.00/mo across 10,000 reports) across 3 priced stages; ...",
  "privacy": "Evaluated in memory with zero retention; inline pipeline stages, private rates, ledger rows, and evaluation figures are never stored.",
  "meta": {
    "generatedAt": "2026-11-06T00:00:00.000Z",
    "source": "database",
    "stageCount": 3,
    "discoverPeers": true
  }
}
```
