---
title: "List a suite's settings history"
method: GET
path: "/projects/{projectId}/eval-suites/{suiteId}/revisions"
tags: ["Eval suites"]
---

# List a suite's settings history

`GET /projects/{projectId}/eval-suites/{suiteId}/revisions`

One entry per committed edit to the suite's settings, newest first: who made it, which STORED fields moved, the note they left, how many runs were launched against it, and the revision group that ties one request's writes together. Rows carry no configuration snapshots. Send a `revisionNumber` back as `expectedRevisionNumber` on `PATCH /eval-suites/{suiteId}` to make that edit a compare-and-set.

## Path parameters

- `projectId` string, required
- `suiteId` string, required

## Query parameters

- `limit` integer
- `cursor` string

## Headers

- `x-mcpjam-eval-vocabulary` '1' | '2'

## Response `200`

Committed settings edits, newest first.

- EvalSuiteRevisionPage
  - `items` EvalSuiteRevision[], required
    - `id` string, required
    - `revisionNumber` integer, required — Monotonic per suite. The suite's own `revisionNumber` is the newest.
    - `source` 'ui' | 'api' | 'cli' | 'file_sync' | 'import' | 'system' | 'unattributed', required — Where the edit came from. `unattributed` is a write nothing claimed.
    - `createdBy` string, nullable — The user id, or null for a write with no human actor.
    - `createdByName` string, nullable — A display name when one is resolvable.
    - `createdAt` integer, required — Epoch milliseconds.
    - `note` string, nullable — The reason the author gave, when they gave one.
    - `changedFields` string[], required — STORED field names, not public API paths.
    - `revisionGroupId` string, nullable — Shared by every revision one request produced, so a PATCH that edited the settings and re-attached the environments reads as one change.
    - `pinnedRunCount` integer, required — Runs launched against this revision, CAPPED. The question is whether runs used this revision; the difference between 100 and 400 does not change the answer, and counting them all would make the list cost grow with the suite's history.
    - `pinnedRunCountCapped` boolean, required — True when `pinnedRunCount` hit the cap and is a floor rather than a count.
  - `nextCursor` string, nullable

## Other responses

- `400` — Malformed body or parameters.
- `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.
- `502` — Could not connect to the target MCP server.

## Changes

- **2026-09-14** `56b9d1dda7ea` — 1 info
  - added the new optional `header` request parameter `x-mcpjam-eval-vocabulary`
- **2026-09-12** `de57cfcdd824` — 1 info
  - added the non-success response with the status `502`
- **2026-09-04** `e60b7e1653e7` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/mcpjam/apis/mcpjam-api/changes/projects/:projectId/eval-suites/:suiteId/revisions/get.md)

---

[API](https://skmtc.dev/mcpjam/apis/mcpjam-api.md) · [All operations](https://skmtc.dev/mcpjam/apis/mcpjam-api/llms.txt) · [OpenAPI document](https://skmtc.dev/mcpjam/apis/mcpjam-api/revisions/a15a9864fb85?raw)