---
title: "Create a experiment"
method: POST
path: "/v4/experiments"
tags: ["Experiments"]
---

# Create a experiment

`POST /v4/experiments`

Create a new experiment

## Request body

- CreateExperiment — Creates a new experiment with the given pipeline ID
  - `name` string — Friendly experiment name
  - `pipelineId` union, required — The ID of the pipeline to create the experiment for, or "default" to use the organization's default pipeline
    - string, uuid
    - 'default'
  - `metadata` object — Optional metadata for the experiment

## Response `200`

Successful response

- Experiment
  - `id` string, uuid, required — Experiment UUID
  - `createdAt` string, required — Creation timestamp (ISO 8601)
  - `updatedAt` string, required — Last update timestamp (ISO 8601)
  - `name` string, nullable, required — Friendly experiment name
  - `pipelineId` string, required — Pipeline UUID
  - `metadata` object, nullable, required — Metadata
  - `resourcePath` string, nullable, required — Resource path to navigate to the experiment

## Other responses

- `400` — Client provided an invalid request for the experiment. Please check the request format and parameters.
- `401` — No valid API key provided.
- `404` — The experiment resource does not exist.
- `500` — Something went wrong on Gentrace's end.

## Changes

- **2025-07-24** `938ac0c5af7b` — 1 breaking, 1 info
  - the `pipelineId` request property type/format changed from `string`/`uuid` to ``/``
  - added `subschema #1, subschema #2` to the `pipelineId` request property `anyOf` list
- **2025-07-22** `765227ffe9ad` — 1 info
  - added the required property `resourcePath` to the response with the `200` status
- **2025-04-28** `76bde656b16e` — 5 breaking, 2 warning
  - the `createdAt` response's property type/format changed from `string`/`date-time` to `string`/`` for status `200`
  - the `updatedAt` response's property type/format changed from `string`/`date-time` to `string`/`` for status `200`
  - removed the required property `branch` from the response with the `200` status
  - removed the required property `commit` from the response with the `200` status
  - …3 more
- **2025-04-22** `610091298e37` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/gentrace/apis/gentrace-api/changes/v4/experiments/post.md)

---

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