---
title: "Create Run"
method: POST
path: "/projects/{projectId}/runs"
---

# Create Run

`POST /projects/{projectId}/runs`

Create a new Run.

## Path parameters

- `projectId` string, required

## Request body

- object
  - `testsetId` string, nullable — The ID of the Testset this Run is testing.
  - `systemVersionId` string, uuid, nullable — The ID of the system version this Run is using.
  - `metricIds` string[], required — The IDs of the metrics this Run is using.

## Response `201`

Run created successfully

- Run — A Run in the Scorecard system.
  - `id` string, required — The ID of the Run.
  - `testsetId` string, nullable, required — The ID of the Testset this Run is testing.
  - `systemId` string, uuid, nullable, required — The ID of the system this Run is using.
  - `systemVersionId` string, uuid, nullable, required — The ID of the system version this Run is using.
  - `metricIds` string[], required — The IDs of the metrics this Run is using.
  - `metricVersionIds` string[], required — The IDs of the metric versions this Run is using.
  - `numRecords` number, required — The number of records in the Run.
  - `numExpectedRecords` number, nullable, required — The number of expected records in the Run. Determined by the number of testcases in the Run's Testset at the time of Run creation.
  - `numScores` number, required — The number of completed scores in the Run so far.
  - `status` 'pending' | 'awaiting_execution' | 'running_execution' | 'awaiting_scoring' | 'running_scoring' | 'awaiting_human_scoring' | 'completed', required — The status of the Run.

## Other responses

- `401` — Error indicating that the request is not authenticated.
- `500` — An internal service error indicating an issue with the Scorecard service.

## Changes

- **2025-09-30** `47c2214e7180` — 1 breaking, 7 info
  - the response property `systemVersionId` became nullable for the status `201`
  - the request property `systemVersionId` became nullable
  - the response property `systemVersionId` became required for the status `201`
  - added the required property `metricVersionIds` to the response with the `201` status
  - …4 more
- **2025-06-10** `f8f811fe2ec9` — 2 warning, 2 info
  - removed the request property `systemConfigId`
  - removed the optional property `systemConfigId` from the response with the `201` status
  - added the new optional request property `systemVersionId`
  - added the optional property `systemVersionId` to the response with the `201` status
- **2025-06-05** `b33acf308c1f` — 1 breaking, 2 info
  - the response property `testsetId` became nullable for the status `201`
  - the request property `testsetId` became nullable
  - the request property `testsetId` became optional
- **2025-04-28** `e3159f1f21c4` — 1 info
  - added the required property `status` to the response with the `201` status

[Change history](https://skmtc.dev/scorecard-ai/apis/scorecard-api/changes/projects/:projectId/runs/post.md)

---

[API](https://skmtc.dev/scorecard-ai/apis/scorecard-api.md) · [All operations](https://skmtc.dev/scorecard-ai/apis/scorecard-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/scorecard-ai/scorecard-api/revisions/121aaa257802/schema)