Eval runs

Get one run's stage analytics

ONE run’s materialized stage-analytics document: where its 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.

The same document the suite listing returns, addressed by run. Use this rather than paging /eval-suites/{suiteId}/stage-analytics to reach a known run: that listing is newest-first, so walking it costs work proportional to how long ago the run finished and cannot answer once the run falls outside the pages read.

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.

404 covers BOTH “this run has no document” and “this run is not visible to you”, and the two are deliberately not distinguished — separating them would confirm that a run exists in a project you cannot see. NOT backfilled either: a run that completed before this shipped has no document, and that absence means UNMEASURED, never a funnel of zeros.

GET

projects

{projectId}

eval-runs

{runId}

stage-analytics

Get one run's stage analytics

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "schemaVersion": 1,
  "measurementUnit": "trial",
  "runId": "<string>",
  "suiteId": "<string>",
  "sourceIterationCount": 1,
  "stageAnalyzerVersion": 2,
  "measurementsSchemaVersion": 2,
  "materializationState": "provisional",
  "createdAt": 1,
  "updatedAt": 1,
  "includedTrials": 1,
  "excludedTrials": {
    "lifecycle": 1,
    "integrity": 1,
    "version": 1,
    "notApplicable": 1,
    "reachUnknown": 1,
    "notMeasured": 1
  },
  "totalTrials": 1,
  "excludedTrialDetail": {
    "notTerminal": 1,
    "skipped": 1,
    "cancelled": 1,
    "setupFailed": 1,
    "timedOut": 1,
    "executionFailed": 1,
    "evaluatorError": 1,
    "chainMissing": 1,
    "chainUnverified": 1,
    "chainVersionAhead": 1,
    "measurementsMissing": 1,
    "measurementsInvalid": 1,
    "measurementsVersionAhead": 1,
    "analyzerMismatch": 1
  },
  "slices": [
    {
      "slice": {
        "dimension": "overall"
      },
      "includedTrials": 1,
      "excludedTrials": {
        "lifecycle": 1,
        "integrity": 1,
        "version": 1,
        "notApplicable": 1,
        "reachUnknown": 1,
        "notMeasured": 1
      },
      "failureCategories": [
        {
          "category": "<string>",
          "count": 2
        }
      ],
      "stages": [
        {
          "stage": "connection",
          "applicable": 1,
          "reached": 1,
          "notReached": 1,
          "reachUnknown": 1,
          "measured": 1,
          "passed": 1,
          "failed": 1,
          "notMeasured": 1,
          "notApplicable": 1,
          "excluded": {
            "lifecycle": 1,
            "integrity": 1,
            "version": 1,
            "notApplicable": 1,
            "reachUnknown": 1,
            "notMeasured": 1
          },
          "reasons": [
            {
              "reason": "<string>",
              "count": 2
            }
          ],
          "latency": {
            "unit": "ms",
            "basis": "evidence_span_union",
            "sampleCount": 2,
            "totalMs": 1,
            "minMs": 1,
            "maxMs": 1
          }
        }
      ]
    }
  ],
  "setup": [
    {
      "phase": "connection",
      "uniqueAttempts": 1,
      "failedAttempts": 1,
      "serverAttributedFailures": 1,
      "impactedTrials": 1,
      "latency": {
        "unit": "ms",
        "basis": "setup_phase_wall",
        "sampleCount": 2,
        "totalMs": 1,
        "minMs": 1,
        "maxMs": 1
      }
    }
  ],
  "runGroupId": "<string>",
  "configRevision": "<string>",
  "caseSetFingerprint": "<string>",
  "organizationId": "<string>",
  "workspaceId": "<string>",
  "projectId": "<string>",
  "runCompletedAt": 1,
  "sourceMaxUpdatedAt": 1,
  "sourceStageAnalyzerVersions": [
    2
  ],
  "sourceMeasurementsSchemaVersions": [
    2
  ],
  "sliceTruncation": [
    {
      "dimension": "intent",
      "distinctValues": 2,
      "retained": 1
    }
  ]
}

Authorizations

Authorization

string

header

required

MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.

Path Parameters

projectId

string

required

ID of the hosted project that contains the server.

runId

string

required

Eval run ID, as returned by POST /eval-runs.

Response

The run's complete stage-analytics document.

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.

schemaVersion

enum<integer>

required

Available options:

1

measurementUnit

enum<string>

required

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.

Available options:

trial

runId

string

required

Minimum string length: 1

suiteId

string

required

Minimum string length: 1

sourceIterationCount

integer

required

How many iterations this materialization actually read.

Required range: x >= 0

stageAnalyzerVersion

integer

required

The analyzer the source chains were ACTUALLY derived at, not the version the reader understands. When included trials disagree this is the newest present.

Required range: x >= 1

measurementsSchemaVersion

integer

required

Required range: x >= 1

materializationState

enum<string>

required

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.

Available options:

provisional,

final

createdAt

integer

required

Required range: x >= 0

updatedAt

integer

required

Required range: x >= 0

includedTrials

integer

required

Trials that contributed observations. Equals the overall slice's own count, and never exceeds totalTrials.

Required range: x >= 0

excludedTrials

object

required

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.

Show child attributes

totalTrials

integer

required

Every trial the materializer saw, included or not.

Required range: x >= 0

excludedTrialDetail

object

required

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.

Show child attributes

slices

object[]

required

Marginal slices in canonical order. Exactly one overall slice, always present and always first.

Maximum array length: 101

Show child attributes

setup

object[]

required

Run-level setup facts, one row per phase that carried a signal. Never two rows for one phase.

Maximum array length: 2

Show child attributes

runGroupId

string

Present when the run is grouped for comparison (a matrix, a schedule).

Minimum string length: 1

configRevision

string

The run's authored-configuration revision. One of three identities a parity claim requires; ABSENCE BLOCKS parity rather than being assumed compatible.

Minimum string length: 1

caseSetFingerprint

string

A digest over the comparable case set this run actually measured. Absence blocks parity, same rule.

Minimum string length: 1

organizationId

string

Minimum string length: 1

workspaceId

string

Minimum string length: 1

projectId

string

Minimum string length: 1

runCompletedAt

integer

When the run reached a terminal status, in epoch milliseconds. The field from/to filter on.

Required range: x >= 0

sourceMaxUpdatedAt

integer

The newest update stamp among those iterations — the staleness handle for a rebuild.

Required range: x >= 0

sourceStageAnalyzerVersions

integer[]

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.

Minimum array length: 2

Required range: x >= 1

sourceMeasurementsSchemaVersions

integer[]

Every distinct measurement schema version among included trials. Same rule as the analyzer versions.

Minimum array length: 2

Required range: x >= 1

sliceTruncation

object[]

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'.

Maximum array length: 3

Show child attributes

⌘I

Get one run's stage analytics

curl --request GET \
  --url https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://app.mcpjam.com/api/v1/projects/{projectId}/eval-runs/{runId}/stage-analytics")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "schemaVersion": 1,
  "measurementUnit": "trial",
  "runId": "<string>",
  "suiteId": "<string>",
  "sourceIterationCount": 1,
  "stageAnalyzerVersion": 2,
  "measurementsSchemaVersion": 2,
  "materializationState": "provisional",
  "createdAt": 1,
  "updatedAt": 1,
  "includedTrials": 1,
  "excludedTrials": {
    "lifecycle": 1,
    "integrity": 1,
    "version": 1,
    "notApplicable": 1,
    "reachUnknown": 1,
    "notMeasured": 1
  },
  "totalTrials": 1,
  "excludedTrialDetail": {
    "notTerminal": 1,
    "skipped": 1,
    "cancelled": 1,
    "setupFailed": 1,
    "timedOut": 1,
    "executionFailed": 1,
    "evaluatorError": 1,
    "chainMissing": 1,
    "chainUnverified": 1,
    "chainVersionAhead": 1,
    "measurementsMissing": 1,
    "measurementsInvalid": 1,
    "measurementsVersionAhead": 1,
    "analyzerMismatch": 1
  },
  "slices": [
    {
      "slice": {
        "dimension": "overall"
      },
      "includedTrials": 1,
      "excludedTrials": {
        "lifecycle": 1,
        "integrity": 1,
        "version": 1,
        "notApplicable": 1,
        "reachUnknown": 1,
        "notMeasured": 1
      },
      "failureCategories": [
        {
          "category": "<string>",
          "count": 2
        }
      ],
      "stages": [
        {
          "stage": "connection",
          "applicable": 1,
          "reached": 1,
          "notReached": 1,
          "reachUnknown": 1,
          "measured": 1,
          "passed": 1,
          "failed": 1,
          "notMeasured": 1,
          "notApplicable": 1,
          "excluded": {
            "lifecycle": 1,
            "integrity": 1,
            "version": 1,
            "notApplicable": 1,
            "reachUnknown": 1,
            "notMeasured": 1
          },
          "reasons": [
            {
              "reason": "<string>",
              "count": 2
            }
          ],
          "latency": {
            "unit": "ms",
            "basis": "evidence_span_union",
            "sampleCount": 2,
            "totalMs": 1,
            "minMs": 1,
            "maxMs": 1
          }
        }
      ]
    }
  ],
  "setup": [
    {
      "phase": "connection",
      "uniqueAttempts": 1,
      "failedAttempts": 1,
      "serverAttributedFailures": 1,
      "impactedTrials": 1,
      "latency": {
        "unit": "ms",
        "basis": "setup_phase_wall",
        "sampleCount": 2,
        "totalMs": 1,
        "minMs": 1,
        "maxMs": 1
      }
    }
  ],
  "runGroupId": "<string>",
  "configRevision": "<string>",
  "caseSetFingerprint": "<string>",
  "organizationId": "<string>",
  "workspaceId": "<string>",
  "projectId": "<string>",
  "runCompletedAt": 1,
  "sourceMaxUpdatedAt": 1,
  "sourceStageAnalyzerVersions": [
    2
  ],
  "sourceMeasurementsSchemaVersions": [
    2
  ],
  "sliceTruncation": [
    {
      "dimension": "intent",
      "distinctValues": 2,
      "retained": 1
    }
  ]
}

API Guides

Endpoints

Get one run's stage analytics

Authorizations

Path Parameters

Response