> ## Documentation Index > Fetch the complete documentation index at: https://docs.mcpjam.com/llms.txt > Use this file to discover all available pages before exploring further. # List a suite's per-run stage analytics > One materialized stage-analytics document per RUN, newest completion first: where trials fell out of the six-stage user-value chain (connection, discovery, selection, tool call, response, user value), overall and sliced marginally by intent, model and host. Each item is one run's COMPLETE document and stands alone. There is deliberately no cross-run aggregate — two funnels averaged together describe no run — so compare runs by rendering them side by side, never by summing these documents. Counts are returned; RATES are not. A zero denominator is `notMeasured`, never `0`, and every excluded observation is counted under a named class so a denominator can never shrink silently. NOT backfilled: a run that completed before this shipped has no document at all, and that absence means UNMEASURED — it is never a funnel of zeros. ## OpenAPI ````yaml /reference/openapi.json get /projects/{projectId}/eval-suites/{suiteId}/stage-analytics openapi: 3.1.0 info: title: MCPJam API version: 1.0.0-preview description: >- Programmatic access to MCP servers saved in your MCPJam projects — live diagnostics (validate, inspect, export) and operations: call tools, render prompts, run eval suites asynchronously and poll their results, and import OAuth tokens. **The API is in preview**: the surface may change while we finish the design. Error `code` values are stable; error `message` strings are not. Write clients that ignore unknown response fields. contact: name: MCPJam url: https://github.com/MCPJam/inspector/issues servers: - url: https://app.mcpjam.com/api/v1 description: Hosted MCPJam security: - bearerAuth: [] tags: - name: Clients description: >- Clients — the named, reusable configurations that define how MCPJam connects to and talks to your MCP servers. The original `/hosts` paths remain as deprecated, ID-only compatibility aliases with their original DTOs and their original (tokenless) write contracts; every alias response carries `Deprecation: true`. New integrations should use `/clients`. - name: Environments description: >- Project environments: named, live-editable execution bundles (one host, an optional standalone server group, optionally pinned skills and plugin versions) that eval suites and journeys run against. Distinct from Sandbox images, which are Computer base images. Reads require project membership; every write requires project admin. - name: Plugins description: >- Agent Plugins imported into a project — read-only inventory and version detail. - name: Skills description: >- Cloud Skills: authored SKILL.md files stored in a project. Read-only here. Environments pin skills by id (`skillSelection.skillIds`) and eval runs pin them with `--compose-skill`, so this surface exists to give an unattended caller those ids; authoring is an app flow behind a beta gate. - name: Sandbox images description: >- Custom Computer images: a digest-pinned Dockerfile built into an immutable image your project's computers boot from. - name: Server diagnostics description: Connect-level health checks against a saved MCP server. - name: Primitives description: 'The server''s MCP primitives: tools, prompts, and resources.' - name: Export description: Full-server snapshots for diffing and CI. - name: Execution description: 'Run the server''s primitives: call tools, render prompts.' - name: Eval runs description: >- Asynchronous eval suite runs: create with 202, poll status, iterations, and traces. - name: Conformance runs description: >- Ingest MCP spec-conformance results from the SDK/CLI into project-owned history. Distinct from Eval runs (authored LLM cases) and from directory readiness. - name: Server connections description: >- Connect an MCP server URL to a project, authorizing in a browser when the server requires it. - name: OAuth description: 'Bring-your-own OAuth: import externally obtained tokens for a server.' - name: Scenarios description: >- Read-only access to the scenarios published from a project: listing, settings, attached servers, and share links. - name: Catalog description: >- Discover the resources the other routes operate on: your account, projects, servers, eval suites, and chat sessions. - name: Tunnels description: >- Relay tunnels that expose local MCP servers through a public URL, registered as first-class project servers (the `mcpjam cloud tunnel` CLI flow). - name: Agent description: >- Headless agent turns over the public API: send a message history, the server runs one assistant turn with project-scoped workspace tools (eval reads + suite creation) on a pinned hosted model, and returns the reply plus created-resource references. - name: Swarms description: >- Personas, journeys and swarm containers — the authoring half of Swarms — plus the model-backed generation that drafts them. - name: Swarm runs description: >- Launching journeys and reading what they produced. Launching SPENDS — see the per-operation notes. - name: Swarm insights description: >- What a swarm run revealed. The scorecard and findings are deterministic and free; requesting wave insights runs models and draws on your shared daily ledger. - name: User testing description: >- Publishing an environment for real visitors, and controlling who can reach it. Several of these NARROW access and take effect immediately. - name: Directory readiness description: >- Grade a saved server against a publisher's listing requirements: Anthropic's connector directory or OpenAI's plugin directory. Reported as lane status and coverage, never as a numeric score, and excluded from `pooledConformanceScore`. Deterministic grading is free; model-backed experience observations are an explicit opt-in that consumes MCPJam credits and can never decide a verdict. - name: Registry description: >- Search the scraped MCP directories (Claude, ChatGPT, and any future source), list curated/org registry cards, and install them into a project. Install writes a `servers` row and provenance — it does not open a live session. There is no catalog-uninstall route: delete the project server instead. Directory reads require a bearer (including minted guest tokens) but do not materialize a user. Card/connection reads and all writes are authed-non-guest. paths: /projects/{projectId}/eval-suites/{suiteId}/stage-analytics: get: tags: - Eval runs summary: List a suite's per-run stage analytics description: >- One materialized stage-analytics document per RUN, newest completion first: where trials fell out of the six-stage user-value chain (connection, discovery, selection, tool call, response, user value), overall and sliced marginally by intent, model and host. Each item is one run's COMPLETE document and stands alone. There is deliberately no cross-run aggregate — two funnels averaged together describe no run — so compare runs by rendering them side by side, never by summing these documents. Counts are returned; RATES are not. A zero denominator is `notMeasured`, never `0`, and every excluded observation is counted under a named class so a denominator can never shrink silently. NOT backfilled: a run that completed before this shipped has no document at all, and that absence means UNMEASURED — it is never a funnel of zeros. operationId: listEvalSuiteStageAnalytics parameters: - $ref: '#/components/parameters/projectId' - $ref: '#/components/parameters/suiteId' - name: from in: query required: false description: >- Inclusive lower bound on the run's completion stamp, in epoch MILLISECONDS (not ISO). Runs that never completed carry no stamp and are excluded by any `from` bound. Must be less than or equal to `to`, or the request is a VALIDATION_ERROR. schema: type: integer minimum: 0 - name: to in: query required: false description: >- Inclusive upper bound on the run's completion stamp, in epoch MILLISECONDS (not ISO). schema: type: integer minimum: 0 - name: runGroupId in: query required: false description: Narrow to one comparison group (a matrix leg, a schedule). schema: type: string minLength: 1 - name: cursor in: query required: false description: Opaque cursor from a previous page's `nextCursor`. schema: type: string - name: limit in: query required: false description: >- Maximum documents to return, 1–100. Defaults to 25 — these documents are large. schema: type: integer minimum: 1 maximum: 100 default: 25 responses: '200': description: >- One page of per-run stage-analytics documents, newest run completion first. An empty `items` means this suite has no materialized documents in the requested window — which is not the same as a run whose stages all measured zero. content: application/json: schema: $ref: '#/components/schemas/EvalStageAnalyticsPage' '400': $ref: '#/components/responses/ValidationError' '401': $ref: '#/components/responses/Unauthorized' '403': $ref: '#/components/responses/Forbidden' '404': $ref: '#/components/responses/NotFound' '429': $ref: '#/components/responses/RateLimited' '500': $ref: '#/components/responses/InternalError' '502': $ref: '#/components/responses/ServerUnreachable' components: parameters: projectId: name: projectId in: path required: true description: ID of the hosted project that contains the server. schema: type: string suiteId: name: suiteId in: path required: true description: Eval suite ID, as returned by `POST /eval-runs`. schema: type: string schemas: EvalStageAnalyticsPage: type: object required: - items properties: items: type: array items: $ref: '#/components/schemas/EvalStageAnalytics' nextCursor: type: string description: Opaque cursor for the next page. Omitted on the last page. EvalStageAnalytics: type: object description: >- One RUN's materialized stage funnel. Counts are stored; rates are DERIVED by the SDK contract's helpers, so a zero denominator stays `notMeasured` and never renders as `0%`. There is no top-level overall, latency or reasons object: the overall funnel is the `overall` slice (always present, always first), latency lives inside each stage tally and each setup row, and reasons live inside each stage tally. required: - schemaVersion - measurementUnit - runId - suiteId - sourceIterationCount - stageAnalyzerVersion - measurementsSchemaVersion - materializationState - createdAt - updatedAt - includedTrials - excludedTrials - totalTrials - excludedTrialDetail - slices - setup properties: schemaVersion: type: integer enum: - 1 measurementUnit: type: string enum: - trial description: >- The literal `trial`, carried rather than assumed. An eval iteration, a user-testing session and a swarm traversal share this stage vocabulary and are NOT the same unit; a consumer merging two documents must check this first. runId: type: string minLength: 1 suiteId: type: string minLength: 1 runGroupId: type: string minLength: 1 description: >- Present when the run is grouped for comparison (a matrix, a schedule). configRevision: type: string minLength: 1 description: >- The run's authored-configuration revision. One of three identities a parity claim requires; ABSENCE BLOCKS parity rather than being assumed compatible. caseSetFingerprint: type: string minLength: 1 description: >- A digest over the comparable case set this run actually measured. Absence blocks parity, same rule. organizationId: type: string minLength: 1 workspaceId: type: string minLength: 1 projectId: type: string minLength: 1 runCompletedAt: type: integer minimum: 0 description: >- When the run reached a terminal status, in epoch milliseconds. The field `from`/`to` filter on. sourceIterationCount: type: integer minimum: 0 description: How many iterations this materialization actually read. sourceMaxUpdatedAt: type: integer minimum: 0 description: >- The newest update stamp among those iterations — the staleness handle for a rebuild. stageAnalyzerVersion: type: integer minimum: 1 description: >- The analyzer the source chains were ACTUALLY derived at, not the version the reader understands. When included trials disagree this is the newest present. sourceStageAnalyzerVersions: type: array minItems: 2 items: type: integer minimum: 1 description: >- Every DISTINCT analyzer version among included trials, ascending. Present ONLY when more than one contributed — a uniform document omits it. A mixed document is not comparable to anything. measurementsSchemaVersion: type: integer minimum: 1 sourceMeasurementsSchemaVersions: type: array minItems: 2 items: type: integer minimum: 1 description: >- Every distinct measurement schema version among included trials. Same rule as the analyzer versions. materializationState: type: string enum: - provisional - final description: >- `provisional` while a judge fanout is still pending — the counts may still move under the reader — and `final` once every applicable fanout has completed. There is no `stale`. createdAt: type: integer minimum: 0 updatedAt: type: integer minimum: 0 includedTrials: type: integer minimum: 0 description: >- Trials that contributed observations. Equals the overall slice's own count, and never exceeds `totalTrials`. excludedTrials: $ref: '#/components/schemas/EvalStageExclusions' totalTrials: type: integer minimum: 0 description: Every trial the materializer saw, included or not. excludedTrialDetail: $ref: '#/components/schemas/EvalStageCoverageDetail' slices: type: array maxItems: 101 description: >- Marginal slices in canonical order. Exactly one `overall` slice, always present and always first. items: $ref: '#/components/schemas/EvalStageAnalyticsSliceRow' setup: type: array maxItems: 2 description: >- Run-level setup facts, one row per phase that carried a signal. Never two rows for one phase. items: $ref: '#/components/schemas/EvalSetupTally' sliceTruncation: type: array maxItems: 3 description: >- Which dimensions hit a cap, and by how much. Present ONLY when a cap bit — a truncated slice array with no such record would read as 'these are all the models'. items: type: object required: - dimension - distinctValues - retained properties: dimension: type: string enum: - intent - model - host distinctValues: type: integer minimum: 1 retained: type: integer minimum: 0 Error: type: object required: - code - message properties: code: type: string description: >- Stable, machine-readable error code. New codes may be added over time; treat unknown codes as non-retryable failures unless the HTTP status says otherwise. enum: - UNAUTHORIZED - FORBIDDEN - NOT_FOUND - CONFLICT - VALIDATION_ERROR - RATE_LIMITED - FEATURE_NOT_SUPPORTED - SERVER_UNREACHABLE - TIMEOUT - OAUTH_REQUIRED - INTERNAL_ERROR message: type: string description: >- Human-readable description. May change between releases — don't match on it. details: type: object description: Optional, unstructured context bag. additionalProperties: true EvalStageExclusions: type: object description: >- How many observations each class removed from ONE denominator. A class that excluded nothing is OMITTED rather than written as 0 — absent and 0 mean the same thing here. properties: lifecycle: type: integer minimum: 0 description: >- The trial never produced a comparable observation: not terminal, skipped, cancelled, timed out, setup-failed, execution failed, or the evaluator itself errored. integrity: type: integer minimum: 0 description: >- A chain or measurement was missing, unverified or rejected at the write boundary. Never coerced into a passing observation. version: type: integer minimum: 0 description: >- Produced by an analyzer or schema version this reader does not understand. Also never coerced. notApplicable: type: integer minimum: 0 description: The stage does not apply to this case at all. reachUnknown: type: integer minimum: 0 description: >- Nothing was captured, so reach could not be decided. Deliberately excluded from the reach denominator. notMeasured: type: integer minimum: 0 description: The stage was reached but nothing decided it. EvalStageCoverageDetail: type: object description: >- The FINE-GRAINED reason a trial was excluded. Run-level only — the coarse six-class tally repeats on every stage of every slice, but 'we could not read the chain' and 'the chain was there and was refused' are different operator actions and are carried once, here. properties: notTerminal: type: integer minimum: 0 skipped: type: integer minimum: 0 cancelled: type: integer minimum: 0 setupFailed: type: integer minimum: 0 timedOut: type: integer minimum: 0 executionFailed: type: integer minimum: 0 evaluatorError: type: integer minimum: 0 chainMissing: type: integer minimum: 0 chainUnverified: type: integer minimum: 0 chainVersionAhead: type: integer minimum: 0 measurementsMissing: type: integer minimum: 0 measurementsInvalid: type: integer minimum: 0 measurementsVersionAhead: type: integer minimum: 0 analyzerMismatch: type: integer minimum: 0 description: >- The chain's analyzer version and its own measurements' disagree — a payload whose two halves came from different analyzers. Always a bug, never a deploy window. EvalStageAnalyticsSliceRow: type: object required: - slice - includedTrials - excludedTrials - failureCategories - stages properties: slice: $ref: '#/components/schemas/EvalStageAnalyticsSlice' includedTrials: type: integer minimum: 0 description: Trials that contributed observations to this slice. excludedTrials: $ref: '#/components/schemas/EvalStageExclusions' failureCategories: type: array description: >- Failure categories over TRIALS in this slice — one bucket per trial, not per stage. A CLOSED vocabulary. items: type: object required: - category - count properties: category: type: string count: type: integer minimum: 1 stages: type: array description: >- Exactly six tallies in canonical stage order. Position is meaning — never re-sort them. minItems: 6 maxItems: 6 items: $ref: '#/components/schemas/EvalStageTally' EvalSetupTally: type: object description: >- One setup phase's facts for this run. RUN-LEVEL, not per-slice: an attempt happens once per run+phase and is copied onto every iteration, so attempts are counted once here while `impactedTrials` — which genuinely varies per trial — is counted distinctly and MAY exceed the attempt count. required: - phase - uniqueAttempts - failedAttempts - serverAttributedFailures - impactedTrials properties: phase: type: string enum: - connection - discovery uniqueAttempts: type: integer minimum: 0 failedAttempts: type: integer minimum: 0 serverAttributedFailures: type: integer minimum: 0 description: >- Failures attributable to the SERVER under a deliberately narrow rule: the signal said `theirs` AND our own egress was positively verified. Anything less is unknown and is not attributed. impactedTrials: type: integer minimum: 0 description: >- DISTINCT trials this phase's failed attempts blocked. May exceed `uniqueAttempts` — that is the point of counting it separately. latency: $ref: '#/components/schemas/EvalSetupLatencyAggregate' EvalStageAnalyticsSlice: description: >- Which population a slice describes. MARGINAL only — there is deliberately no intent x model x host cross-product, because a funnel computed over two trials is not a comparison. oneOf: - type: object required: - dimension properties: dimension: type: string enum: - overall - type: object required: - dimension - intent properties: dimension: type: string enum: - intent intent: type: - string - 'null' minLength: 1 description: >- `null` is the UNLABELLED slice and is a real slice, not an omission. Never display the raw null — untagged cases are often the majority, and dropping them would make the intent funnel describe a subset while looking like the whole. - type: object required: - dimension - provider - model properties: dimension: type: string enum: - model provider: type: string minLength: 1 model: type: string minLength: 1 - type: object required: - dimension - hostKey properties: dimension: type: string enum: - host hostKey: type: string minLength: 1 description: Stable across renames. The join key, not the display name. hostName: type: string minLength: 1 executionEngine: type: string minLength: 1 description: >- `emulated` or `harness:`. ABSENT means not recorded — not emulated. EvalStageTally: type: object description: >- One stage's counts within one slice. Every field is a COUNT of trials, and the arithmetic is enforced: `passed + failed = measured`, `measured + notMeasured = reached`, `reached + notReached + reachUnknown = applicable`. required: - stage - applicable - reached - notReached - reachUnknown - measured - passed - failed - notMeasured - notApplicable - excluded - reasons properties: stage: type: string enum: - connection - discovery - selection - call - response - userValue applicable: type: integer minimum: 0 description: >- Trials for which this stage applies at all (included minus notApplicable). reached: type: integer minimum: 0 notReached: type: integer minimum: 0 reachUnknown: type: integer minimum: 0 description: >- Reached-ness could not be decided. Excluded from the reach denominator: a trial we captured nothing for is not evidence of a drop-off. measured: type: integer minimum: 0 description: Reached AND decided — `passed + failed`. passed: type: integer minimum: 0 failed: type: integer minimum: 0 notMeasured: type: integer minimum: 0 description: Reached but nothing decided it. notApplicable: type: integer minimum: 0 excluded: $ref: '#/components/schemas/EvalStageExclusions' reasons: type: array description: >- Why stages landed where they did, by reason code. A CLOSED vocabulary — render what arrives, never widen it. items: type: object required: - reason - count properties: reason: type: string count: type: integer minimum: 1 latency: $ref: '#/components/schemas/EvalStageLatencyAggregate' EvalSetupLatencyAggregate: type: object description: >- The same aggregate shape over a setup phase's wall clock. Sampled once per ATTEMPT, never once per copied iteration. required: - unit - basis - sampleCount - totalMs - minMs - maxMs properties: unit: type: string enum: - ms basis: type: string enum: - setup_phase_wall sampleCount: type: integer minimum: 1 totalMs: type: number minimum: 0 minMs: type: number minimum: 0 maxMs: type: number minimum: 0 EvalStageLatencyAggregate: type: object description: >- Sums, not means. `totalMs` + `sampleCount` is strictly more information than a mean and is MERGEABLE. There is no p99 and no confidence interval on purpose. An aggregate with no samples is OMITTED, never zeroed. required: - unit - basis - sampleCount - totalMs - minMs - maxMs properties: unit: type: string enum: - ms basis: type: string enum: - evidence_span_union description: >- How the span was measured. Always display the basis beside the number. sampleCount: type: integer minimum: 1 description: At least one. Never exceeds the tally's `reached`. totalMs: type: number minimum: 0 minMs: type: number minimum: 0 maxMs: type: number minimum: 0 responses: ValidationError: description: Malformed body or parameters. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: VALIDATION_ERROR message: Invalid JSON body Unauthorized: description: >- Missing, invalid, revoked, or orphaned key (`UNAUTHORIZED`) — or the **target MCP server** needs an OAuth grant (`OAUTH_REQUIRED`), which is a property of the server, not your key. content: application/json: schema: $ref: '#/components/schemas/Error' examples: badKey: summary: Invalid or revoked key value: code: UNAUTHORIZED message: Invalid API key oauthRequired: summary: Target server needs an OAuth grant value: code: OAUTH_REQUIRED message: Server requires OAuth authorization Forbidden: description: Key is valid but not allowed to do this. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: FORBIDDEN message: You do not have access to this project NotFound: description: Unknown project, server, or resource. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: NOT_FOUND message: Server not found RateLimited: description: >- Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter. headers: Retry-After: description: Seconds to wait before retrying. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/Error' example: code: RATE_LIMITED message: API key rate limit exceeded. Slow down and retry. InternalError: description: Something failed on MCPJam's side. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: INTERNAL_ERROR message: Unexpected internal error ServerUnreachable: description: Could not connect to the target MCP server. content: application/json: schema: $ref: '#/components/schemas/Error' example: code: SERVER_UNREACHABLE message: Failed to connect to server securitySchemes: bearerAuth: type: http scheme: bearer description: >- MCPJam API key (`sk_…`). Create one at [Settings → API keys](https://app.mcpjam.com/settings/api-keys). Guest sessions cannot use the API, and API keys cannot manage other API keys. ````