Get run status
Run status, result, and summary. Poll until status is terminal (completed, failed, cancelled or timed_out). grading is not terminal — every trial has finished and the run is held for its gating judge, with result still pending — so keep polling.
Authorizations
MCPJam API key (sk_…). Create one at Settings → API keys. Guest sessions cannot use the API, and API keys cannot manage other API keys.
Headers
Which vocabulary this request and its response speak. Absent means 1, which is byte-for-byte today's contract: the same request fields, the same refusals, the same response projection. 2 is the canonical vocabulary. Any other value is a 400 with code: "VALIDATION_ERROR".
Today it decides one thing: the spelling of an evaluator's policy role. Vocabulary 1 accepts and returns gating; vocabulary 2 accepts both spellings and returns the canonical required. Sending required without the header is a 400, deliberately — vocabulary 1 is not widened to meet vocabulary 2 half way, because a boundary that accepts a spelling it does not announce is one two implementations can disagree about.
A response that varies by vocabulary sends Vary: x-mcpjam-eval-vocabulary.
1, 2 Path Parameters
ID of the hosted project that contains the server.
Eval run ID, as returned by POST /eval-runs.
Response
The run.
Poll until TERMINAL. The four terminal statuses are completed, failed, cancelled and timed_out. grading is NOT terminal: every trial has finished and the run is being held for its gating judge — up to 30 minutes — with result still pending. A poller that stops at grading reports a run with no verdict as though it had one.
pending, running, grading, completed, failed, cancelled, timed_out Run origin, STAMPED BY THE SERVER and not settable by a caller. Every run created through this API is api — including one launched by the CLI, by a GitHub Actions job, or by an MCP agent, because from the server's side all three are API calls. The caller's own claim about which of those it is rides on launcher. schedule and github_check are written by the platform's scheduled-eval and PR-check workers; benchmark marks a Connector Bench matrix cell and is hidden from project run lists.
ui, api, sdk, schedule, github_check, benchmark Epoch milliseconds.
Durable execution client, omitted on older runs without a descriptor. Separate from launcher identity.
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.
passed, failed, inconclusive, null The run's DECLARED launcher — what the launching process says it is, sent as the x-mcpjam-launcher request header at launch. A LABEL, never an authorization input: source above is the stamped, unforgeable answer and attribution below is the verified one. Allowlisted to the three origins the server cannot observe for itself. ABSENT when the launcher declared nothing, which is not the same as ui.
VERIFIED agent attribution, minted by the platform from the credential this run authenticated with — never from anything the caller sent. The audit-grade half of the pair: launcher says what the client called itself, surface says what the credential proved. Descriptive only; nothing reads it to decide access. ABSENT when the credential carried no attribution claims.
Epoch milliseconds, null until terminal.
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.
valid, invalid, null Which criterion decided this run, frozen at run start. 2 is PER-CASE GRADING; ABSENT means the SUITE-WIDE ACCURACY THRESHOLD — result cannot then be inconclusive, because that criterion has no validity phase, and there is no verdictSummary. The 2 is a wire spelling, not a version a caller upgrades to. A caller gating on fractions or on validity must read this FIRST rather than assume a missing summary means a clean run.
2 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.
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.
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.
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.
Model the run actually executed with. Absent on pre-attribution rows.
client_default inherited the host model; override used the environment's modelId; case used the sole model in the case snapshot.
client_default, override, case 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.
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".
Advisory LLM graders on this run. Present on the DETAIL response only — lists stay compact — and absent on deployments that predate the envelope.
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.
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".
2003264Bounded caller metadata; preserved as descriptive data, never authorization.
Bounded CI attribution and source revision metadata.
Case-scoped run evaluator observations with source and definition identity.

