---
title: "Replace an experiment"
method: PUT
path: "/api/v2/experiments/{experiment_id}/"
tags: ["experiments"]
---

# Replace an experiment

`PUT /api/v2/experiments/{experiment_id}/`

Replace editable fields for an experiment.

## Path parameters

- `experiment_id` string, required

## Headers

- `Authorization` string, required

## Request body

- object
  - `dataset_id` string — Dataset ID to process.
  - `workflow` ApiV2ExperimentsExperimentIdPutRequestBodyContentApplicationJsonSchemaWorkflowItems[] — Workflow tasks to run for each dataset row.
    - `type` 'prompt' | 'completion' | 'eval' | 'condition' | 'wait' | 'duplicate', required — Workflow step type. Use `eval` for inline evaluation steps; legacy `evaluator` input is normalized to `eval`.
    - `config` object, required — Configuration for this workflow step. `prompt` accepts `prompt_id` or `prompt_slug`; `completion` accepts model generation settings; `wait` pauses until results are submitted; `duplicate` reuses dataset input/output.
  - `evaluator_ids` string[] — Preferred evaluator identifiers for scoring. Mutually exclusive with `evaluator_workflow_ids`.
  - `evaluator_slugs` string[] — Backward-compatible alias for `evaluator_ids`. If both are provided, `evaluator_ids` takes precedence.
  - `evaluator_workflow_ids` string[] — WorkflowVersion IDs configured for eval-only scoring. Mutually exclusive with evaluator IDs/slugs.
  - `experiment_id` string — Optional client-provided experiment ID. The backend generates one when omitted.
  - `name` string — Experiment name.
  - `description` string — Experiment description.
  - `span_workflow_name` string — Root workflow span name.
  - `enable_tracing` boolean — Whether to create trace logs.
  - `batch_size` integer — Batch size for processing.
  - `concurrency` integer — Number of concurrent workers.
  - `generation_method` string — Optional evaluation generation method override.

## Response `200`

Updated experiment.

- ExperimentsReplaceExperimentResponse200
  - `id` string, required — Experiment ID.
  - `name` string, required — Experiment name.
  - `description` string, nullable — Experiment description.
  - `dataset` string, nullable — Dataset ID associated with the experiment.
  - `dataset_id` string, nullable — Dataset ID associated with the experiment.
  - `dataset_name` string, nullable — Dataset name, when available.
  - `workflow_count` integer — Number of workflow steps.
  - `status` string, required — Experiment execution status.
  - `progress` number, double — Execution progress percentage.
  - `created_at` string, date-time, required
  - `started_at` string, date-time, nullable
  - `completed_at` string, date-time, nullable
  - `tags` object[] — Tags attached to the experiment.
  - `workflow` ApiV2ExperimentsExperimentIdPutResponsesContentApplicationJsonSchemaWorkflowItems[] — Workflow tasks configured for the experiment.
    - `type` 'prompt' | 'completion' | 'eval' | 'condition' | 'wait' | 'duplicate', required — Workflow step type. Use `eval` for inline evaluation steps; legacy `evaluator` input is normalized to `eval`.
    - `config` object, required — Configuration for this workflow step. `prompt` accepts `prompt_id` or `prompt_slug`; `completion` accepts model generation settings; `wait` pauses until results are submitted; `duplicate` reuses dataset input/output.
  - `evaluator_ids` string[] — Evaluator IDs used for scoring.
  - `evaluator_slugs` string[] — Backward-compatible evaluator identifiers stored by the backend.
  - `evaluator_workflow_ids` string[] — Eval-only workflow versions used for scoring.
  - `batch_size` integer
  - `concurrency` integer
  - `enable_tracing` boolean
  - `error_message` string, nullable — Failure details when status is failed.

## Other responses

- `400` — Bad Request
- `401` — Unauthorized - Missing or invalid authentication
- `404` — Not Found

---

[API](https://skmtc.net/keywordsai/apis/api-reference.md) · [All operations](https://skmtc.net/keywordsai/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/keywordsai/api-reference/revisions/4e064cf81dae/schema)