DOCUMENTATION

The p90 guide.

Practical instructions for connecting data, operating the dashboard, using pricing tools, working with the API and SDK, and understanding the p90 vocabulary.

01What p90 is

p90 monitors the cost of serving an AI product across a seven-layer cost model, detects economic anomalies, simulates margin trajectories, and generates ranked pricing recommendations. A human approval gate sits at the end of every agent cycle. Nothing changes pricing until a person selects and approves an option.

The name is the thesis. AI systems fail at the p90 and p95 of the cost distribution, not at the average. The gap between your median user's cost and your most expensive user's cost is what determines whether pricing survives contact with real usage.

•Cost math, tier boundaries, and pricing floors are deterministic. The same inputs produce the same numbers.
•Narrative copy and tier copy can use an LLM. Core calculations continue to work when no model key is configured.
•Workspace-scoped: each product you monitor is a workspace with its own cost model, metrics, and recommendations.

02Core concepts

Variance is the real enemy

Two users paying the same price can cost very differently to serve. Averages hide this. p90 tracks the p90 cost-per-request alongside the average, and the ratio between them, because the tail is what turns a healthy margin underwater.

Cost propagates across seven layers

Tokens are the visible fraction of AI cost. Retrieval, context construction, orchestration, retries, concurrency, and evaluation affect different parts of the serving path. A change in one layer can add direct work or amplify request size, repeated execution, capacity pressure, or downstream validation.

Price for the worst reasonable day

If pricing only works when users behave nicely, it does not work. p90 simulates adverse scenarios by default and evaluates the tail rather than only the median, so a floor can hold when usage spikes.

03Getting started

01Open the dashboard. With no data it shows an empty state offering demo data or a real connection.
02Click ‘Use Demo Mode’ to populate clearly-labelled simulated metrics, or ‘Run Demo’ in the header to watch a full agent cycle produce a recommendation.
03Go to Connect from the dashboard to name your product. This creates a workspace where you can connect a real data source.
04Set up your seven-layer cost model so thresholds derive from your real economics instead of demo defaults.
05Watch the agent loop run. When it surfaces a recommendation, review the three options and approve one.

The demo runs entirely on simulated data, marked ‘Simulated’ in the header. Nothing you see in demo mode reflects real spend until you connect a source.

04Production URLs and verification

p90.tech is the public frontend. It hosts the landing page, dashboard, authentication screens, documentation, reports, and public SEO pages. It is not the API host.

•Frontend: https://p90.tech
•FastAPI and SDK ingestion: https://p90-backend-6k66.onrender.com
•Authenticated MCP over Streamable HTTP: https://p90-mcp-http-prod.onrender.com/mcp
•OTLP trace gateway: https://p90-otel-gateway.onrender.com/v1/traces
•Supabase project URL: configured separately through NEXT_PUBLIC_SUPABASE_URL and SUPABASE_URL

01For browser authentication, set the Supabase Site URL to https://p90.tech and allow https://p90.tech/auth/callback. Keep localhost callback URLs only for local development.
02For browser API access, the backend must allow the exact origin https://p90.tech through CORS_ALLOWED_ORIGINS.
03For Salesforce, register the backend callback https://p90-backend-6k66.onrender.com/api/integrations/salesforce/callback. Do not use the frontend domain as the OAuth callback.
04For Search Console, verify p90.tech and submit https://p90.tech/sitemap.xml.
05For SDK, MCP, and OTLP integrations, use their service endpoint above and keep credentials in server or CI secret storage.

Use the dedicated service URLs above. The frontend domain is not an API proxy, so replacing backend, SDK, MCP, OTLP, or OAuth URLs with p90.tech will fail until a separate proxy is deployed. For the complete product workflow, use the step-by-step usage tutorial linked below.

05Connecting a data source

p90 monitors your actual metrics, not a simulation, once a source is connected. You only need one observability source to start; add more any time from Settings.

•Langfuse is the recommended first connection. It supplies retry rate, context-token distributions, and latency percentiles.
•Helicone and LangSmith are alternatives for retry and token data.
•Anthropic and OpenAI usage APIs populate Layer 4 model-execution cost.
•Stripe, Orb, Metronome, and Chargebee supply revenue so p90 can calculate gross margin rather than cost alone.
•Warehouse & cloud billing (Vertex, Bedrock, Databricks, Redshift) and Salesforce (OAuth) for enterprise cohorts.
•The p90 SDK is the direct integration path. It requires a workspace ingestion key.
•MCP gives an AI assistant workspace context and explicitly confirmed operations. The local stdio server and the authenticated production Streamable HTTP service are both available. MCP is not a telemetry ingestion path.

Credentials are verified live and stored in a Fernet-encrypted keystore. Only a last-4 hint is kept in the database; the full key is never exposed back to the client.

06Workspace operations

01Start with one workspace per product or business unit. Each workspace has its own metrics, cost model, integrations, approvals, branding, and exports.
02Use one organization for a portfolio of products. Account and Org list every attached product; select a product card to change the active dashboard workspace.
03Open Connect and verify a data source. The status bar should change from Simulated to Live only after the workspace reports a connected source.
04Complete Setup before relying on price-floor or variance-headroom results. Missing cost inputs are allowed, but they make the model less representative of the product.
05Review the 24-hour gross margin chart and the latest metrics. A chart is populated only when the workspace has gross-margin history for that period.
06When a recommendation is pending, use Review the fix or the approval dialog. Read the anomaly, simulation, options, and Decision Evidence before approving or dismissing it.
07Use Report for retrospective summaries and audit exports. Save branding before generating stakeholder-facing PDF exports.

Product documentation ends at workspace use. Developers and operators can find deployment, environment, health, CORS, Supabase, and incident guidance in the operator documentation.

07Product context

Save product context on Connect to tell p90 what you are building, where pricing stands, and what you need to learn first. This does not replace telemetry or the seven-layer cost model. It helps p90 choose relevant comparisons and explain the next action in business terms.

•Product type selects the peer category used by benchmark views.
•Pricing stage changes the framing of pricing guidance, such as exploration, usage economics, or enterprise capacity.
•Monitoring goal shapes the generated pricing-page copy, relevant FAQ, dashboard focus, and first suggested action.
•Saved context appears at the top of the dashboard and is included in supported report exports so readers know what the analysis was prepared for.
•Observed telemetry and the configured cost model remain authoritative for margins, thresholds, prices, and projections.

You can revise product context at any time from Connect. Regenerating a pricing plan uses the latest saved context together with the current cost model and observed data.

08The seven-layer cost model

Your cost model is the workspace COGS configuration. Every field is optional. Fill in what you know and p90 derives cost per request and baseline margin from the available inputs. The seven layers are:

•Layer 1, Data Preparation: Data ingestion, preprocessing, transformation, preparation and related work performed before retrieval or model execution.
•Layer 2, Retrieval & Memory: Vector search, database retrieval, external search, memory systems and related data-access operations.
•Layer 3, Context Construction: Context assembly, prompt construction, history management, reranking, compression and context preparation.
•Layer 4, Model Execution: Inference, model API calls, token usage, accelerator compute and hosted or self-hosted model execution.
•Layer 5, Orchestration & Retries: Workflow orchestration, agent coordination, tool-call sequencing, retries, repeated calls and recovery behaviour.
•Layer 6, Parallelism & Concurrency: Concurrent requests, parallel agents, provisioning pressure and infrastructure required for simultaneous execution.
•Layer 7, Evaluation & Guardrails: Evaluation calls, policy checks, safety checks, secondary verification, quality checks and other validation work.

Once saved, p90 recomputes your COGS-per-request, baseline gross margin, and variance headroom, and uses them to set monitoring thresholds tuned to your economics.

Configure a cost model by API

A workspace admin can create a workspace-scoped service API key with the api:write scope from Connect. Use it from a server, CI job, or secret manager, never from browser or mobile code. POST the same cost-model fields used by Setup to /api/modules/cogs. The key selects its workspace automatically, so do not send an X-Workspace-ID header.

curl -X POST https://p90-backend-6k66.onrender.com/api/modules/cogs \
  -H "Authorization: Bearer $P90_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "layer4_primary_model": "gpt-4.1-mini",
    "layer4_cost_per_1k_input_tokens": 0.0004,
    "layer4_cost_per_1k_output_tokens": 0.0016,
    "layer4_avg_output_tokens": 320,
    "current_price_per_request_cents": 4.0
  }'

There is no dedicated cost-model CLI command yet. MCP supports cost-model configuration when the workspace administrator grants the separate mcp:configure scope. The set_cost_model tool requires explicit confirmation and uses the same seven-layer fields as Setup and the API.

09The agent loop

The agent runs continuously as a four-node graph, with a human pricing authority boundary after recommendation generation. It decides when to surface evidence and options.

01Monitor: evaluates the latest metrics against your thresholds, including retry rate, p90/avg ratio, context bloat, concurrency, and margin floor.
02Detect: attributes a breach to the specific cost layer responsible, so you see cause rather than only a symptom.
03Simulate: projects the worst-case margin trajectory if the anomaly continues over a 30-day horizon.
04Reason: composes three ranked pricing options, conservative, moderate, and aggressive, with structured Decision Evidence and a recommended pick.
05Approve: you review the options and Decision Evidence, then select one. Approval records authority to proceed; it does not claim that a downstream pricing change has been applied.

Every node execution is written to an append-only agent log, and every approved decision is versioned with the economic trigger that caused it.

10Reading the dashboard

•Status bar: system status, live or simulated data source, current scenario, pending approvals, and a time-to-value counter until the first approved recommendation.
•Maturity Score: a 0 to 100 pricing-maturity grade across data, alignment, defensibility, and responsiveness.
•Metrics feed and Margin chart: the live economic state and its trend, with an optional P&L Scenario Overlay.
•Agent log: the running narrative of Monitor, Detect, Simulate, and Reason.
•Approval panel: slides up when a recommendation is pending and pre-selects the agent's recommended option.
•Decision log and Reports: the audit trail plus exportable plain-language retrospectives.

11Pricing tools

Pricing Floor

The lowest price that preserves your target margin under three behaviors: median, p90, and worst reasonable day. The recommended floor is the p90 scenario, because that is where real products break.

Variance Headroom

How much cost variance your current price absorbs before margin turns negative, expressed in cents and a status band (comfortable / tight / negative). Recomputed each cycle and on every cost-model save.

Tier design & pricing page

Open Overview > Plan > Pricing Page Draft and choose Generate pricing page. p90 first reads the configured seven-layer cost model, target margin, cost per request, and deterministic Starter, Growth, and Scale boundaries. It then creates a customer-facing plan with monthly price or Custom pricing, included usage, overage guidance, customer description, features, and a call to action.

•A cost model is required for a live pricing plan. Without one, p90 shows a setup action instead of presenting explanation text as a completed plan.
•The draft is editable. Change plan names, prices, included-use descriptions, features, calls to action, FAQs, and the usage explanation before reviewing the customer preview.
•The editor shows the workspace source as connected or simulated, plus the target margin, COGS, and economic guardrails used to form the plan.
•Export is blocked when an edited numeric price falls below the target margin, required plan copy is missing, or no cost model is configured. The panel exports Markdown or HTML only. It does not publish pricing or change billing.
•Demo mode uses the browser-local demo cost model. Configure it at /dashboard/setup?demo=true before generating a simulated plan.
•Saving the draft creates the workspace pricing-plan record used by the P&L Scenario Overlay and pricing reports. Select a saved tier in the overlay to project that plan's price per included request.
•The overlay requires observed request volume from telemetry or a metric snapshot. It does not multiply active users by a fixed requests-per-user estimate.

Outcome-based readiness

A 0–100 assessment across four dimensions (reliability, outcome-measurement infrastructure, cost predictability, and margin stability) telling you whether you can credibly price on outcomes yet.

12Enterprise features

Deal structuring

Enter an enterprise prospect's expected volume, concurrency, and SLA needs. p90 generates Conservative, Target, and Aggressive capacity-based structures with cost to serve, projected margin, annual contract value, key terms, and a recommended pick. This is available to Scale and Enterprise tiers at /dashboard/enterprise/deals.

White-label export

Brand your playbook and stakeholder exports with your logo, primary color, company name, and a terminology map (e.g. ‘gross margin’ → ‘contribution margin’) for board and investor decks.

Organizations & teams

Run multiple product lines under one organization with role-based access (owner, admin, analyst, viewer). The org overview at /dashboard/org shows every product's status, margin, and pending recommendations, with team invites.

13Governance & defensibility

Every pricing decision in p90 records the economic anomaly that triggered it, the three options considered, structured Decision Evidence, and the approval record. Records are timestamped and attributed.

•Architecture Decision Log: record cost-affecting engineering decisions with their economic rationale through a GitHub PR acknowledgement link or manual entry.
•Decision export: a JSON, CSV, or PDF record of decision history for internal review, board discussion, or investor diligence.
•Decision Defensibility: a live score of how audit-ready your pricing governance is.

14Pricing Intelligence Network

Workspaces can opt in to an anonymized benchmark network. Each contributor is stored only as a one-way SHA-256 hash of its workspace id plus a secret salt, so a contributor cannot be reverse-identified. Only aggregated period averages are shared, never per-request data.

Benchmarks are surfaced only once a category has at least ten contributors, so no benchmark ever leaks a small sample.

15The p90 SDK

The fastest way to send real telemetry. Wrap your LLM client once; token counts, context size, retries, and per-user cost stream to p90 asynchronously, never blocking or adding latency.

The SDK sends events to the FastAPI service at https://p90-backend-6k66.onrender.com/api/sdk by default. Override the endpoint when using a private network or a future API proxy. The public frontend domain is not an ingestion endpoint.

import { p90 } from "p90-sdk";

const client = p90.wrap(new Anthropic(), {
  workspaceId: process.env.P90_WORKSPACE_ID,
  apiKey: process.env.P90_API_KEY,
});

// use client exactly as before; telemetry is recorded after each call

16MCP and service API keys

P90 has two programmatic access paths. The SDK sends product telemetry. MCP gives an AI assistant read access to monitoring context and, when explicitly scoped, the ability to trigger a monitoring cycle, approve a named recommendation, or configure the workspace cost model. Each capability has a separate service-key scope.

01In Connect, create an MCP connection as a workspace admin. P90 shows the generated key once.
02Store the key in your local assistant configuration or CI secret manager. Never put it in browser code or a repository.
03Use mcp:read for monitoring context. Add mcp:operate only for explicitly confirmed monitoring or recommendation actions. Add mcp:configure separately when the assistant should read or update the seven-layer cost model. set_cost_model always requires confirm=true.
04P90 supports the local stdio server and an authenticated Streamable HTTP service at https://p90-mcp-http-prod.onrender.com/mcp. The public liveness check is https://p90-mcp-http-prod.onrender.com/healthz/live; protected readiness and tools/list checks require a workspace service key.
05For server and CI integrations, create a service API key with api:read and, only where needed, api:write. Keys are workspace-scoped, hashed at rest, and revocable.

{
  "mcpServers": {
    "p90": {
      "command": "python",
      "args": ["-m", "mcp.server"],
      "env": {
        "P90_API_BASE_URL": "https://p90-backend-6k66.onrender.com",
        "P90_MCP_API_KEY": "p90_your_workspace_scoped_key"
      }
    }
  }
}

A service key represents one workspace, not an organization owner. It cannot manage organization membership or ownership. Revoke a key when its owner, environment, or integration changes. MCP liveness only proves that the HTTP service is running; protected readiness and tools/list checks prove that the service can authenticate and reach the P90 API.

17API reference

Browser requests use the active workspace plus a Supabase session. Server, CI, and MCP requests can use a workspace-scoped service API key in the Authorization bearer header, removing the need for an interactive login or X-Workspace-ID header.

Metrics & agent

GET  /api/metrics/latest        # recent snapshots + thresholds
GET  /api/metrics/summary       # status, margin trend, pending count
GET  /api/agent/logs?limit=50   # append-only agent log
POST /api/agent/approve         # { recommendation_id, action, selected_option }

Cost model & pricing

POST /api/modules/cogs              # upsert the seven-layer cost model
GET  /api/modules/maturity-score    # 0-100 pricing maturity
GET  /api/modules/pricing-floor     # target-margin floor scenarios
GET  /api/modules/variance-headroom # headroom in cents + status band
GET  /api/modules/tier-boundaries   # Starter / Growth / Scale
POST /api/modules/pricing-page      # customer-facing pricing copy and plan tiers
POST /api/modules/pricing-plan      # generate and persist a plan draft
GET  /api/modules/pricing-plan       # retrieve the saved plan for projections
PUT  /api/modules/pricing-plan       # save edited plan copy
POST /api/modules/pl-overlay        # project a change onto the P&L
POST /api/modules/deal-structure    # three enterprise deal structures

The pricing-plan endpoints are the shared source for a saved draft. They store the generated copy beside deterministic usage limits, suggested prices, overage rates, margin checks, and guardrails. The P&L overlay, saved pricing-plan report, and enterprise deal calculations can then identify the plan version they used. Projections use observed request volume and cost attribution; they do not infer volume from active users.

Governance & workspace

GET  /api/modules/arch-log          # architecture decision log
GET  /api/modules/defensibility     # decision-defensibility score
GET  /api/modules/compliance-export # decision audit export
GET  /api/workspace/me              # workspace + integration status
POST /api/sdk/telemetry             # SDK event ingestion (rate-limited)
POST /api/service-keys              # issue a workspace service key (admin)
GET  /api/service-keys              # list workspace service keys (admin)
POST /api/service-keys/{key_id}/revoke # revoke a service key

GLOSSARY

The p90 vocabulary.

The economics terms p90 uses throughout the product and these docs.

p90 cost/request: The cost per request at the 90th percentile. It shows a realistic expensive usage point instead of the average alone.
fully loaded COGS: The estimated cost to serve one request across the configured seven cost layers.
variance: The spread between lower-cost and higher-cost usage patterns that makes one price serve customers with different costs.
variance headroom: The cost increase the current price can absorb before gross margin reaches zero.
pricing floor: The minimum price that preserves the configured target margin under a selected cost scenario.
anomaly: A monitored metric that crosses its configured threshold and needs investigation.
recommendation: A proposed response to an anomaly, with alternatives and supporting Decision Evidence.
alternative: A materially different response presented alongside the leading recommendation.
approval: A human decision selecting or dismissing a recommendation. It does not prove that implementation occurred.
implementation: The separately tracked action taken after approval, such as applying a pricing or product change.
Decision Evidence: A structured explanation of the trigger, observed values, affected cohort, attribution, assumptions, alternatives, and decision state.
pricing maturity: A 0 to 100 diagnostic score showing how well the workspace measures, explains, governs, and learns from pricing decisions.
outcome-pricing readiness: A readiness assessment for pricing on measurable outcomes, based on reliability, measurement, cost-model completeness, and contractual readiness.
simulation: A calculated projection of what may happen if a measured cost condition continues. It is not an observed result.
realised outcome: The measured result after an approved intervention, compared with its baseline and projection.
affected cohort: The product, plan, route, or user group associated with the monitored economic change.
p90 / p95: The 90th / 95th percentile of a distribution. p90 uses the p90 cost-per-request as the signal that matters, because AI systems fail at the tail, not the average.
Variance: The spread between your cheapest and most expensive users. High variance means uniform pricing subsidizes the expensive tail with the cheap median.
Seven-layer cost stack: p90's model of AI COGS: data preparation, retrieval and memory, context construction, model execution, orchestration and retries, parallelism and concurrency, and evaluation and guardrails. Cost propagates through the stack without assuming every layer multiplies every other layer.
COGS: Cost of goods sold. In p90, this is the fully loaded cost to serve one request across all seven layers.
Gross margin: (Price − COGS) / Price. p90 computes true gross margin only once a revenue source is connected.
Power-user concentration: The share of total cost driven by your most expensive users. Rising concentration means a small cohort is carrying disproportionate cost.
Retry rate: The fraction of requests that retry. A Layer-5 (orchestration) signal; spikes cascade into model-execution cost.
Context bloat: Growth in average context tokens per call as prompts, history, and retrieved chunks accumulate. It is a Layer 3 cost driver.
Concurrency peak: The maximum simultaneous requests. Beyond your provisioned baseline it forces over-provisioning overhead (Layer 6).
Layer attribution: Detect-node output that maps an anomaly to the cost layer causing it, so you fix cause rather than symptom.
Time-to-Value (TTV): Days from workspace creation to your first approved recommendation.
Payback period: How long the cumulative margin improvement from implemented recommendations takes to pay back, given estimated MRR.
Semantic cache hit rate: The share of requests served from a semantic cache. A drop raises effective Layer-4 cost and is monitored as a signal.
Spend cap: A per-user or per-workspace ceiling recommended to bound worst-case cost exposure.
Per-user cost attribution: Cost rolled up per end-user (one-way hashed) from SDK telemetry, surfacing which users drive spend.
Tier boundaries: Deterministic Starter / Growth / Scale usage cutoffs derived from your cost distribution.
Pricing page draft: An editable customer-facing pricing plan generated from the workspace cost model. It includes plan prices, usage limits, features, customer descriptions, calls to action, FAQs, and exportable Markdown or HTML. It is not a published pricing page and does not change billing.
Deal structure: One of three capacity-based enterprise pricing proposals (Conservative / Target / Aggressive) with margin modeling.
ACV: Annual contract value. It is a deal's monthly revenue times the contract length.
Workspace: One product you monitor, with its own cost model, metrics, and recommendations. Identified by the X-Workspace-ID header.
Organization: A parent account owning multiple workspaces, with role-based access and a subscription tier.
RBAC roles: owner > admin > analyst > viewer. Roles gate sensitive actions such as approving changes or inviting members.
Decision Defensibility: A score of how audit-ready your pricing governance is. It considers Decision Evidence, human approval, documented anomalies, and outcome tracking.
Architecture Decision Log: A record of cost-affecting engineering decisions with their economic rationale, populated from GitHub PRs or manual entry.
Pricing Intelligence Network: An opt-in, anonymized benchmark network. Contributors are one-way hashed; benchmarks appear only past ten contributors per category.
Retrospective: A deliberate, calendar-cadence review (month / quarter / half-year) aggregating snapshots into margin trends and a plain-English narrative.