---
title: "Authenticate and record an eval start"
method: POST
path: "/projects/{projectId}/eval-ingest/start-run"
tags: ["Eval runs"]
---

# Authenticate and record an eval start

`POST /projects/{projectId}/eval-ingest/start-run`

## Request

- Base URL: `https://app.mcpjam.com/api/v1`
- URL: `https://app.mcpjam.com/api/v1/projects/{projectId}/eval-ingest/start-run`
- Auth: HTTP bearer

Called by official SDK, CLI and Vitest runners before executing an eval. Requires an organization API key or saved-login bearer. Records only start metadata, creates no dashboard run, and applies no debit or quota draw. Planned iterations are intent, not completed usage. Reuse the runStartId for retries of the same logical run; changed metadata with the same ID returns 409. Replay protection is retained for the lifetime of the owning scope. The gateway passes the backend status and receipt through unchanged.

## Path parameters

- `projectId` string, required

## Request body

- object
  - `runStartId` string, uuid, required
  - `surface` 'sdk' | 'cli' | 'vitest', required
  - `clientVersion` string, required
  - `providers` string[], required
  - `usedClientProfile` union, required
    - boolean
    - 'unknown'
  - `plannedIterations` integer, required

## Response `200`

Authenticated start receipt. Identical retries return the same receipt.

- object
  - `ok` true, required
  - `runStartId` string, uuid, required
  - `organizationId` string, required
  - `projectId` string, required

## 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.
- `409`: The resource is not in a state that accepts this write — a stale `expectedRevision`, a duplicate name, or an environment that cannot currently be launched. The request was well-formed; re-read the resource and retry.
- `413`: The start metadata exceeds the 8 KiB limit.
- `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.
- `504`: The target MCP server connected but didn't respond in time.

## Changes

- **2026-10-19** `cc4d79ad5ff9`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/mcpjam/apis/mcpjam-api/changes/projects/:projectId/eval-ingest/start-run/post.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/abec02af60a4?raw)