Get run status

GET

projects

{projectId}

eval-runs

{runId}

Get run status

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

import requests

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

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}', 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}",
  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}"

	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}")

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

{
  "id": "<string>",
  "suiteId": "<string>",
  "status": "pending",
  "source": "ui",
  "createdAt": 123,
  "runNumber": 123,
  "result": "passed",
  "summary": {
    "total": 123,
    "passed": 123,
    "failed": 123,
    "passRate": 123
  },
  "notes": "<string>",
  "completedAt": 123,
  "scoreIntegrity": "valid",
  "verdictPolicyVersion": 2,
  "verdictSummary": {},
  "verdictPolicyIntegrityError": "<string>",
  "environment": {
    "id": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "runGroupId": "<string>",
  "effectiveModelId": "<string>",
  "modelSource": "client_default",
  "executionEngine": "<string>",
  "insights": {
    "schemaVersion": 1,
    "scope": {
      "kind": "eval_run",
      "id": "<string>",
      "runId": "<string>",
      "scenarioId": "<string>",
      "windowStartAt": 123,
      "windowEndAt": 123
    },
    "status": "not_available",
    "reasonCode": "<string>",
    "retryable": true,
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "generatedAt": 123,
    "updatedAt": 123,
    "summary": "<string>",
    "coverage": {
      "unit": "iterations",
      "analyzed": 123,
      "total": 123,
      "truncated": true,
      "lowConfidence": true,
      "gradedCount": 123,
      "feedbackCount": 123
    },
    "findings": [
      {
        "id": "<string>",
        "signalFingerprint": "<string>",
        "title": "<string>",
        "category": "unknown",
        "attribution": "unknown",
        "actionTarget": "investigate",
        "actionability": "informational",
        "severity": "info",
        "confidence": "low",
        "observed": "<string>",
        "recommendation": "<string>",
        "acceptanceCriteria": [
          "<string>"
        ],
        "affected": {
          "count": 123,
          "total": 123,
          "unit": "iterations"
        },
        "evidence": [
          {
            "kind": "tool_error",
            "excerpt": "<string>",
            "sessionId": "<string>",
            "iterationId": "<string>",
            "toolName": "<string>",
            "errorCode": "<string>"
          }
        ],
        "rootCause": "<string>",
        "patternSlug": "<string>",
        "target": {
          "serverId": "<string>",
          "surface": "description",
          "snapshotHash": "<string>",
          "toolName": "<string>",
          "fieldPath": "<string>",
          "currentDefinition": {
            "truncated": true,
            "description": "<string>",
            "inputSchemaJson": "<string>",
            "outputSchemaJson": "<string>"
          }
        }
      }
    ],
    "truncation": {
      "truncated": true,
      "omittedFindings": 123,
      "omittedEvidence": 123,
      "contractTruncated": true
    },
    "runHealth": {
      "targets": [
        {
          "subjectKind": "environment",
          "subjectId": "<string>",
          "subjectLabel": "<string>",
          "attempted": 123,
          "succeeded": 123,
          "failed": 123,
          "rateLimited": 123
        }
      ]
    }
  },
  "judges": {
    "goalCompletion": {
      "status": "pending",
      "errorCode": "<string>",
      "summary": "<string>",
      "generatedAt": 123,
      "modelUsed": "<string>",
      "threshold": 123,
      "cases": [
        {
          "caseKey": "<string>",
          "score": 123,
          "passed": true,
          "reason": "<string>",
          "rubricHits": [
            "<string>"
          ],
          "iterationId": "<string>"
        }
      ]
    },
    "groundedness": {
      "status": "pending",
      "errorCode": "<string>",
      "summary": "<string>",
      "generatedAt": 123,
      "modelUsed": "<string>",
      "threshold": 123,
      "cases": [
        {
          "caseKey": "<string>",
          "score": 123,
          "passed": true,
          "reason": "<string>",
          "unsupportedClaims": [
            "<string>"
          ],
          "iterationId": "<string>"
        }
      ]
    }
  },
  "gateWaiver": {
    "id": "<string>",
    "suiteId": "<string>",
    "runId": "<string>",
    "reason": "<string>",
    "expiresAt": 123,
    "createdAt": 123,
    "createdBy": "<string>",
    "createdByEmail": "<string>",
    "revokedAt": 123,
    "revokedBy": "<string>",
    "active": true,
    "policySnapshot": {
      "minimumPassRate": 123
    }
  },
  "importEligibility": {
    "status": "legacy",
    "gateable": true,
    "importedCaseCount": 123,
    "claimedExactCaseIds": [
      "<string>"
    ],
    "approvedApproximationCaseIds": [
      "<string>"
    ],
    "approvedApproximationReceipts": [
      {
        "testCaseId": "<string>",
        "approvedBy": "<string>",
        "approvedAt": 123,
        "reason": "<string>",
        "caseKey": "<string>",
        "sourceCaseKey": "<string>"
      }
    ],
    "issues": [
      {
        "code": "<string>",
        "testCaseId": "<string>",
        "caseKey": "<string>",
        "toolName": "<string>"
      }
    ]
  }
}

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.

string

required

suiteId

string

required

status

enum<string>

required

Poll until terminal: completed, failed, or cancelled.

Available options:

pending,

running,

completed,

failed,

cancelled

source

enum<string>

required

Run origin. API-created runs are api.

Available options:

ui,

api,

sdk

createdAt

number

required

Epoch milliseconds.

runNumber

integer | null

result

enum<string> | null

Verdict once terminal. inconclusive exists only under verdictPolicyVersion: 2 and is NOT a failure: the run did not measure the server well enough to say (too few gradeable trials, too many evaluator errors), so a gate that folds it into failed reports a defect the run never observed. Read verdictSummary.reasons for the check that withheld the verdict.

Available options:

passed,

failed,

inconclusive,

null

summary

object | null

Show child attributes

notes

string | null

completedAt

number | null

Epoch milliseconds, null until terminal.

scoreIntegrity

enum<string> | null

Whether the run's score evidence verified at ingest. TRI-STATE, and the third state matters: valid means the backend checked and definitions and results agree; invalid means they do not; null (or absent) means NO VERDICT was produced, on a deployment that predates integrity checking. A score gate must treat null exactly like invalid — absent evidence is not valid evidence.

Available options:

valid,

invalid,

null

verdictPolicyVersion

enum<integer>

The verdict policy this run was decided under, frozen at run start. ABSENT means legacy percent-threshold grading — result cannot then be inconclusive and there is no verdictSummary. A caller gating on fractions or on validity must read this FIRST rather than assume a missing summary means a clean run.

Available options:

2

verdictSummary

object

How a policy-2 verdict was reached: the resolved validity policy, the measured completion and evaluator-error rates with their denominators and exclusions, the per-case and per-execution-variant aggregates, and the exact reasons. Absent when the run is legacy, or when the stored summary failed contract validation at the boundary — a partially-valid decision is never published, because a gate cannot tell a missing field from a satisfied check.

verdictPolicyIntegrityError

string

Why a policy-2 run could not be decided from its own evidence (a missing or malformed policy snapshot, mixed evaluator configs). Accompanies an inconclusive result; it is never a task failure.

environment

object · null · null

The environment revision this run is pinned to. null on a legacy run that recorded none — always present, so a caller never has to distinguish absent from unpinned.

Show child attributes

runGroupId

string

Shared by every per-target run from the same fan-out launch. Absent on a single-target launch and on rows created before run groups.

effectiveModelId

string

Model the run actually executed with. Absent on pre-attribution rows.

modelSource

enum<string>

client_default inherited the host model; override used the environment's modelId.

Available options:

client_default,

override

executionEngine

string

Which engine executed the run: emulated (the platform's own turn loop) or harness:<id> (a real agent runtime such as Claude Code). ABSENT means the run recorded no engine — a run created before the platform attributed one. Treat that as UNKNOWN, never as emulated: those are different claims, and the runs whose engine was never recorded are exactly the ones a reader must not vouch for.

insights

object

The common actionable-insights envelope. Present on the DETAIL response only — lists stay compact — and absent when the caller may not have it or the deployment cannot produce one. Treat absence exactly like status: "not_available".

Show child attributes

judges

object

Advisory LLM graders on this run. Present on the DETAIL response only — lists stay compact — and absent on deployments that predate the envelope.

Show child attributes

gateWaiver

object | null

The waiver currently in force over this run's gate, or null. Gated on being able to VIEW the run, deliberately not on being able to grant a waiver — a waiver only its grantors can see is not a visible one. Carried on the run so a client computing its own gate can fold a waiver in and name it, without a second round trip.

Show child attributes

importEligibility

object

Whether a run's imported cases carry evidence a gate may rely on. Computed by the platform from the run's OWN frozen snapshot, never from the suite's current cases — recomputing from those would let a later edit change what a finished run is allowed to prove. legacy means the run contains no imported cases at all (every native run, forever) and is gateable unchanged; eligible means every imported case carries a valid frozen decision; incomplete means the evidence cannot be trusted, which makes the run NOT GATEABLE and is not a test verdict. The whole field is ABSENT on deployments that predate import eligibility — a different fact from legacy, and one a gate must read as "no opinion, behave as before".

Show child attributes

⌘I

Get run status

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

import requests

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

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}', 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}",
  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}"

	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}")

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

{
  "id": "<string>",
  "suiteId": "<string>",
  "status": "pending",
  "source": "ui",
  "createdAt": 123,
  "runNumber": 123,
  "result": "passed",
  "summary": {
    "total": 123,
    "passed": 123,
    "failed": 123,
    "passRate": 123
  },
  "notes": "<string>",
  "completedAt": 123,
  "scoreIntegrity": "valid",
  "verdictPolicyVersion": 2,
  "verdictSummary": {},
  "verdictPolicyIntegrityError": "<string>",
  "environment": {
    "id": "<string>",
    "name": "<string>",
    "revision": 123
  },
  "runGroupId": "<string>",
  "effectiveModelId": "<string>",
  "modelSource": "client_default",
  "executionEngine": "<string>",
  "insights": {
    "schemaVersion": 1,
    "scope": {
      "kind": "eval_run",
      "id": "<string>",
      "runId": "<string>",
      "scenarioId": "<string>",
      "windowStartAt": 123,
      "windowEndAt": 123
    },
    "status": "not_available",
    "reasonCode": "<string>",
    "retryable": true,
    "error": {
      "code": "<string>",
      "message": "<string>"
    },
    "generatedAt": 123,
    "updatedAt": 123,
    "summary": "<string>",
    "coverage": {
      "unit": "iterations",
      "analyzed": 123,
      "total": 123,
      "truncated": true,
      "lowConfidence": true,
      "gradedCount": 123,
      "feedbackCount": 123
    },
    "findings": [
      {
        "id": "<string>",
        "signalFingerprint": "<string>",
        "title": "<string>",
        "category": "unknown",
        "attribution": "unknown",
        "actionTarget": "investigate",
        "actionability": "informational",
        "severity": "info",
        "confidence": "low",
        "observed": "<string>",
        "recommendation": "<string>",
        "acceptanceCriteria": [
          "<string>"
        ],
        "affected": {
          "count": 123,
          "total": 123,
          "unit": "iterations"
        },
        "evidence": [
          {
            "kind": "tool_error",
            "excerpt": "<string>",
            "sessionId": "<string>",
            "iterationId": "<string>",
            "toolName": "<string>",
            "errorCode": "<string>"
          }
        ],
        "rootCause": "<string>",
        "patternSlug": "<string>",
        "target": {
          "serverId": "<string>",
          "surface": "description",
          "snapshotHash": "<string>",
          "toolName": "<string>",
          "fieldPath": "<string>",
          "currentDefinition": {
            "truncated": true,
            "description": "<string>",
            "inputSchemaJson": "<string>",
            "outputSchemaJson": "<string>"
          }
        }
      }
    ],
    "truncation": {
      "truncated": true,
      "omittedFindings": 123,
      "omittedEvidence": 123,
      "contractTruncated": true
    },
    "runHealth": {
      "targets": [
        {
          "subjectKind": "environment",
          "subjectId": "<string>",
          "subjectLabel": "<string>",
          "attempted": 123,
          "succeeded": 123,
          "failed": 123,
          "rateLimited": 123
        }
      ]
    }
  },
  "judges": {
    "goalCompletion": {
      "status": "pending",
      "errorCode": "<string>",
      "summary": "<string>",
      "generatedAt": 123,
      "modelUsed": "<string>",
      "threshold": 123,
      "cases": [
        {
          "caseKey": "<string>",
          "score": 123,
          "passed": true,
          "reason": "<string>",
          "rubricHits": [
            "<string>"
          ],
          "iterationId": "<string>"
        }
      ]
    },
    "groundedness": {
      "status": "pending",
      "errorCode": "<string>",
      "summary": "<string>",
      "generatedAt": 123,
      "modelUsed": "<string>",
      "threshold": 123,
      "cases": [
        {
          "caseKey": "<string>",
          "score": 123,
          "passed": true,
          "reason": "<string>",
          "unsupportedClaims": [
            "<string>"
          ],
          "iterationId": "<string>"
        }
      ]
    }
  },
  "gateWaiver": {
    "id": "<string>",
    "suiteId": "<string>",
    "runId": "<string>",
    "reason": "<string>",
    "expiresAt": 123,
    "createdAt": 123,
    "createdBy": "<string>",
    "createdByEmail": "<string>",
    "revokedAt": 123,
    "revokedBy": "<string>",
    "active": true,
    "policySnapshot": {
      "minimumPassRate": 123
    }
  },
  "importEligibility": {
    "status": "legacy",
    "gateable": true,
    "importedCaseCount": 123,
    "claimedExactCaseIds": [
      "<string>"
    ],
    "approvedApproximationCaseIds": [
      "<string>"
    ],
    "approvedApproximationReceipts": [
      {
        "testCaseId": "<string>",
        "approvedBy": "<string>",
        "approvedAt": 123,
        "reason": "<string>",
        "caseKey": "<string>",
        "sourceCaseKey": "<string>"
      }
    ],
    "issues": [
      {
        "code": "<string>",
        "testCaseId": "<string>",
        "caseKey": "<string>",
        "toolName": "<string>"
      }
    ]
  }
}

API Guides

Endpoints

Authorizations

Path Parameters

Response