Experiments API Reference
Complete REST API reference for the experiment tracking endpoints at /api/v1/experiments.
Endpoints Summary
| Method | Path | Description |
|---|---|---|
POST | /experiments | Create a new experiment |
GET | /experiments | List experiments with filtering |
GET | /experiments/:id | Get experiment by ID |
PATCH | /experiments/:id | Update experiment metadata |
DELETE | /experiments/:id | Soft-delete (archive) experiment |
POST | /experiments/:id/restore | Restore archived experiment |
POST | /experiments/runs | Create a new run |
GET | /experiments/runs | List runs in an experiment |
GET | /experiments/runs/:id | Get run by ID |
POST | /experiments/runs/:id/log-metrics | Log metrics to run |
POST | /experiments/runs/:id/log-params | Log parameters to run |
POST | /experiments/runs/:id/log-batch | Batch log metrics/params/tags |
POST | /experiments/runs/:id/log-artifact | Upload artifact file |
POST | /experiments/runs/:id/end | End a run |
POST | /experiments/runs/compare | Compare multiple runs |
POST /experiments
Create a new experiment.
Request Body:
{
"name": "string (required, 1-255 chars)",
"description": "string (optional, max 1000 chars)",
"artifact_location": "string (optional, S3 URI)",
"tags": {"key": "value"}
}Response: 201 Created with ExperimentResponse
GET /experiments
List experiments with filtering.
Query Parameters:
| Parameter | Type | Default | Description |
|---|---|---|---|
search | string | null | Search by name (case-insensitive) |
lifecycle_stage | string | active | Filter: active or deleted |
limit | int | 100 | Max results (1-1000) |
offset | int | 0 | Pagination offset |
Response: 200 OK with ExperimentListResponse
POST /experiments/runs
Create a new run within an experiment.
Request Body:
{
"experiment_id": "string (required)",
"name": "string (optional)",
"description": "string (optional)",
"tags": {"key": "value"}
}Response: 201 Created with RunResponse
POST /experiments/runs/:run_id/log-metrics
Log metrics to a run.
Request Body:
{
"metrics": {"metric_name": 0.95},
"step": 10,
"timestamp": 1707723600000
}Response: 200 OK
POST /experiments/runs/:run_id/log-batch
Batch log metrics, parameters, and tags.
Request Body:
{
"metrics": [{"key": "loss", "value": 0.34, "step": 1}],
"params": [{"key": "lr", "value": "0.01"}],
"tags": [{"key": "type", "value": "baseline"}]
}Response: 200 OK with counts of logged items
POST /experiments/runs/:run_id/log-artifact
Upload an artifact file (multipart form).
Parameters:
| Parameter | Type | Description |
|---|---|---|
file | File (required) | The artifact file |
artifact_path | string (query) | Subdirectory within artifacts |
Response: 200 OK
POST /experiments/runs/compare
Compare multiple runs.
Request Body:
{
"run_ids": ["id1", "id2", "id3"],
"metrics": ["val_accuracy", "val_loss"]
}Constraints: 2-10 run IDs
Response: 200 OK with CompareRunsResponse
Error Codes
| Status | Meaning |
|---|---|
400 | Invalid request parameters |
403 | Tenant access denied |
404 | Experiment or run not found |
500 | Internal server error |
Source Files
| File | Path |
|---|---|
| Experiments Router | data-plane/ml-service/src/api/experiments.py |