> ## Documentation Index > Fetch the complete documentation index at: https://docs.zespan.com/llms.txt > Use this file to discover all available pages before exploring further. # Outcome summary by agent or model, joined to cost > Returns one row per distinct value of `dimension` (agent name or model name), summarizing every outcome reported in `[now - range, now]`: total outcomes, successes, total value, and the real LLM cost of the traces those outcomes are attributed to, plus two derived ratios (`costPerSuccess`, `valuePerDollar`). Backs the Value dashboard page's stat bar, chart, and breakdown table. Cost is joined at read time from `llm_events` and is **not** windowed by `range` — a trace's cost is fixed at ingestion and never corrected, unlike an outcome, so only which outcomes count toward a row is affected by the time window; the cost attributed to those outcomes' traces is not. A trace touching more than one model has its outcome attributed to an arbitrary one of them when `dimension=model` — outcomes are recorded at the trace level, not the span level, so a genuinely multi-model trace's outcome is not fanned out across every model it used. **Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires the `dashboard:read` permission — the same auth model as Blast Radius. ## OpenAPI ````yaml /api-reference/openapi.yaml get /v1/projects/{id}/outcomes/summary openapi: 3.1.0 info: title: Zespan Public API version: 1.0.0 description: > The Zespan Public API covers the endpoints that customers call directly or through the Zespan SDKs: trace ingestion (native and OpenTelemetry), prompt management, datasets and dataset runs, and the runtime guardrails check. All endpoints authenticate with a project API key sent in the `x-api-key` header. Create and manage API keys from the project settings in the Zespan dashboard. servers: - url: https://api.zespan.com description: Zespan production API security: - ApiKeyAuth: [] tags: - name: Ingestion description: Send traces and events to Zespan. - name: OpenTelemetry description: OTLP-compatible ingestion endpoints. - name: Prompts description: Manage versioned prompts and their labels, tags, and folders. - name: Datasets description: Read datasets and manage dataset runs used for experiments and scoring. - name: Guardrails description: Runtime guardrail evaluation. - name: SDK / CLI support description: > Small support endpoints consumed by the SDKs and @zespan/cli rather than called directly by application code. - name: Blast Radius description: > The prompt/agent/model/policy/evaluator/alert dependency graph backing the pre-release impact check and the evaluator-delete gate in the dashboard. Session-authenticated (dashboard cookie), not `x-api-key`. - name: Outcomes description: > Report business outcomes (a deflected ticket, an avoided refund, an SLA met) attributed to a trace, and read them back summarized by agent or model, joined to real trace cost. Backs the Value dashboard page. The ingest endpoint is `x-api-key`-authenticated like the rest of ingestion; the two read endpoints are session-authenticated (dashboard cookie) like Blast Radius. - name: Compliance description: > Generate audit-ready evidence documents (a per-agent Compliance Card, or SOC 2 control evidence) from recorded platform data, and re-verify a generated document's citations against live data. Session-authenticated (dashboard cookie), not `x-api-key`, gated by `compliance:read` / `compliance:generate` permissions and the Pro plan or above (the framework listing is the one exception — no project scope and no plan gate, since a customer deciding whether to upgrade needs to see what they'd get). - name: Models description: > Per-model usage, cost, latency, and error-rate rollups for a project, including the lifecycle overlay described under the Model Lifecycle tag. Session-authenticated (dashboard cookie), not `x-api-key`, gated by `dashboard:read`. - name: Model Lifecycle description: > Findings from the daily model deprecation scan, which matches models a project actually calls against a curated, bundled catalogue of provider-announced deprecation and retirement dates. Every figure on a finding (call volume, cost, affected agents/prompts, cost comparison against a named successor) is measured from real trace data — there is no quality-delta or regression-comparison endpoint, because nothing in this API invokes a model on the caller's behalf. Session-authenticated (dashboard cookie), not `x-api-key`: reading findings and the catalogue requires `dashboard:read`, dismissing a finding requires `alerts:manage`. paths: /v1/projects/{id}/outcomes/summary: get: tags: - Outcomes summary: Outcome summary by agent or model, joined to cost description: > Returns one row per distinct value of `dimension` (agent name or model name), summarizing every outcome reported in `[now - range, now]`: total outcomes, successes, total value, and the real LLM cost of the traces those outcomes are attributed to, plus two derived ratios (`costPerSuccess`, `valuePerDollar`). Backs the Value dashboard page's stat bar, chart, and breakdown table. Cost is joined at read time from `llm_events` and is **not** windowed by `range` — a trace's cost is fixed at ingestion and never corrected, unlike an outcome, so only which outcomes count toward a row is affected by the time window; the cost attributed to those outcomes' traces is not. A trace touching more than one model has its outcome attributed to an arbitrary one of them when `dimension=model` — outcomes are recorded at the trace level, not the span level, so a genuinely multi-model trace's outcome is not fanned out across every model it used. **Authenticated with a dashboard session (browser cookie), not `x-api-key`**, and requires the `dashboard:read` permission — the same auth model as Blast Radius. operationId: getOutcomeSummary parameters: - name: id in: path required: true schema: type: string format: uuid description: Project id. - name: range in: query schema: type: string enum: - 24h - 7d - 30d - 90d default: 30d description: Lookback window for which outcomes are counted. - name: dimension in: query schema: type: string enum: - agent - model default: agent description: Which dimension to group rows by. responses: '200': description: Outcome summary rows for the project, grouped by `dimension`. content: application/json: schema: $ref: '#/components/schemas/OutcomeSummaryResponse' '403': description: >- Not authenticated with a dashboard session, or lacks `dashboard:read`. content: application/json: schema: $ref: '#/components/schemas/Error' '404': $ref: '#/components/responses/NotFound' security: [] components: schemas: OutcomeSummaryResponse: type: object properties: rows: type: array items: $ref: '#/components/schemas/OutcomeSummary' required: - rows Error: type: object properties: error: type: string description: Human-readable error message. example: Unauthorized code: type: string description: Machine-readable error code, when present. example: rate_limit_exceeded required: - error OutcomeSummary: type: object properties: name: type: string description: > The dimension's value for this row — an agent name or a model name, depending on the request's `dimension`. totalOutcomes: type: integer successes: type: integer valueUsd: type: number costUsd: type: number costPerSuccess: type: number nullable: true description: Null when there are zero successes to divide cost across. valuePerDollar: type: number nullable: true description: Null when cost is zero. required: - name - totalOutcomes - successes - valueUsd - costUsd - costPerSuccess - valuePerDollar responses: NotFound: description: Resource not found. content: application/json: schema: $ref: '#/components/schemas/Error' securitySchemes: ApiKeyAuth: type: apiKey in: header name: x-api-key description: >- Project API key. Manage keys in the Zespan dashboard under project settings. ````