--- title: "Get run status" method: GET path: "/projects/{projectId}/eval-runs/{runId}" tags: ["Eval runs"] --- # Get run status `GET /projects/{projectId}/eval-runs/{runId}` Run status, result, and summary. Poll until `status` is terminal (`completed`, `failed`, or `cancelled`). ## Path parameters - `projectId` string, required - `runId` string, required ## Response `200` The run. - EvalRun - `id` string, required - `suiteId` string, required - `runNumber` integer, nullable - `status` 'pending' | 'running' | 'completed' | 'failed' | 'cancelled', required — Poll until terminal: `completed`, `failed`, or `cancelled`. - `result` 'passed' | 'failed' | 'null', nullable — Pass/fail verdict once terminal. - `summary` object, nullable - `total` integer - `passed` integer - `failed` integer - `passRate` number - `source` 'ui' | 'api' | 'sdk', required — Run origin. API-created runs are `api`. - `notes` string, nullable - `createdAt` number, required — Epoch milliseconds. - `completedAt` number, nullable — Epoch milliseconds, `null` until terminal. - `scoreIntegrity` 'valid' | 'invalid' | 'null', nullable — 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. - `environment` EvalRunEnvironment, nullable — The project environment a run is pinned to, at the revision resolved when it launched. `null` for a legacy run that used the suite's saved server selection. - `id` string, required - `name` string, nullable - `revision` integer, nullable — The environment revision the run executed against. - `insights` InsightsEnvelope — The common insights envelope, shared by eval runs, swarm waves and user-testing windows. One shape for three producers, so a caller writes the reading code once. An ABSENT envelope and `status: "not_available"` mean the same thing and both are normal: the field is an enrichment, and a caller who may not have it gets the resource without it rather than an error. - `schemaVersion` 1, required - `scope` InsightScope, required — What this envelope is about. The extra fields depend on `kind`. - `kind` 'eval_run' | 'swarm_wave' | 'user_testing_window', required - `id` string, required - `runId` string — `swarm_wave` only. - `scenarioId` string — `user_testing_window` only. - `windowStartAt` integer — `user_testing_window` only. - `windowEndAt` integer — `user_testing_window` only. - `status` 'not_available' | 'not_requested' | 'pending' | 'completed' | 'failed', required — `not_available` means this deployment cannot produce insights at all — treat an ABSENT envelope the same way. `not_requested` means nobody has asked. `pending` means one is running: poll, do not re-request. - `reasonCode` string, nullable, required - `retryable` boolean, required — Whether asking again could produce a different answer. False on a `failed` envelope means the input, not the attempt, was the problem. - `error` object, nullable, required - `code` string, required - `message` string, required - `generatedAt` integer, nullable, required - `updatedAt` integer, nullable, required - `summary` string, nullable, required - `coverage` object, required — READ THIS BEFORE QUOTING ANY FINDING. `truncated` and `lowConfidence` are the difference between "this happens" and "this happened in the part we looked at". - `unit` 'iterations' | 'sessions', required - `analyzed` integer, required - `total` integer, required - `gradedCount` integer - `feedbackCount` integer - `truncated` boolean, required — The analysis saw `analyzed` of `total`, not all of it. - `lowConfidence` boolean, required — Too little was analyzed to generalize. Findings still stand as observations of what WAS seen. - `findings` ActionableFinding[], required - `id` string, required — Stable remediation id (`rf_<16 hex>`). Survives dynamic error values, so the same problem keeps the same id across runs — dismiss it once and it stays dismissed. - `signalFingerprint` string, required — The registry signal this derives from. Several findings can share one. - `title` string, required - `category` 'unknown' | 'tool_contract' | 'tool_runtime' | 'capability_gap' | 'workflow' | 'agent_behavior' | 'test_design' | 'environment', required - `attribution` 'unknown' | 'server_contract' | 'server_runtime' | 'server_capability' | 'agent_or_prompt' | 'test_design' | 'environment', required — WHOSE problem this is. `server_*` points at the MCP server; `agent_or_prompt` and `test_design` point back at the caller. - `actionTarget` 'investigate' | 'mcp_server' | 'agent_configuration' | 'eval_case' | 'environment', required — What you would change to fix it. - `actionability` 'informational' | 'investigate' | 'ready', required — `ready` means the finding names a specific target and change. `investigate` means it does not yet. `informational` means there is nothing to do. - `severity` 'info' | 'low' | 'medium' | 'high', required - `confidence` 'low' | 'medium' | 'high', required - `observed` string, required — DETERMINISTIC observation — counts and identities, never model prose. This is the part you can verify yourself. - `rootCause` string - `recommendation` string, required - `acceptanceCriteria` string[], required — How you would know the fix worked. - `affected` object, required — How much of the analyzed population hit this. Read it as a ratio — `1/40` and `38/40` are different problems. - `count` integer, required - `total` integer, required - `unit` 'iterations' | 'sessions', required - `patternSlug` string - `target` object — Present only when a server (and, for tool surfaces, a tool) resolved against the pinned snapshot. Required for `mcp_server` / `ready`. - `serverId` string, required - `toolName` string - `surface` 'description' | 'input_schema' | 'output_schema' | 'handler' | 'server_instructions' | 'capability', required - `fieldPath` string - `snapshotHash` string, required — The pinned snapshot the target resolved against, so a finding cannot silently re-point at a definition that changed after it was written. - `currentDefinition` object - `description` string - `inputSchemaJson` string - `outputSchemaJson` string - `truncated` boolean, required - `evidence` ActionableFindingEvidence[], required - `sessionId` string - `iterationId` string - `kind` 'tool_error' | 'transcript' | 'feedback' | 'judge' | 'contrast', required - `excerpt` string, required — Scrubbed and clipped at the producer. Never a full transcript. - `toolName` string - `errorCode` string - `runHealth` object — Swarm only. Launch outcomes never appear as findings — a run that could not start is an operational fact, not something the server under test did. - `targets` object[], required - `subjectKind` 'environment' | 'host', required - `subjectId` string, required - `subjectLabel` string, required - `attempted` integer, required - `succeeded` integer, required - `failed` integer, required - `rateLimited` integer, required - `truncation` object, required — What this RESPONSE dropped to stay a sane size, as distinct from what the ANALYSIS did not look at (`coverage`). - `truncated` boolean, required - `omittedFindings` integer, required - `omittedEvidence` integer, required - `contractTruncated` boolean, required ## Other responses - `401` — 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. - `403` — Key is valid but not allowed to do this. - `404` — Unknown project, server, or resource. - `429` — Per-key rate limit exceeded (60 requests/minute sustained, bursts up to 10). Honor `Retry-After` and back off with jitter. - `500` — Something failed on MCPJam's side. --- [API](https://skmtc.net/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.net/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/mcpjam/mcpjam-api/revisions/d3adfe49fbbf/schema)