Experiments

Create, manage, and compare ML experiments. Experiments provide a structured way to track model training runs, hyperparameter configurations, and results across your machine learning projects.

All endpoints require authentication via X-API-Key header (external) or JWT Bearer token (internal platform services via auth-proxy) and the appropriate scope.

---

Experiment Object

{
  "id": "exp_abc123",
  "name": "Sentiment Analysis v2",
  "description": "Comparing transformer architectures for sentiment classification",
  "status": "running",
  "owner": "user_456",
  "organizationId": "org_xyz",
  "tags": ["nlp", "sentiment", "production"],
  "pinned": true,
  "runCount": 12,
  "bestRunId": "run_789",
  "isPublic": false,
  "sharedWith": ["user_789"],
  "createdAt": "2025-01-15T10:30:00Z",
  "updatedAt": "2025-02-01T14:22:00Z"
}

---

GET /api/v1/experiments

List all experiments accessible to the authenticated user.

Scope: ml-workbench:read

Query Parameters

Parameter	Type	Required	Description
search	string	No	Search by experiment name or description
status	string	No	Filter by status: draft, running, completed, failed
tag	string	No	Filter by tag
pinned	boolean	No	Filter by pinned status (true or false)
limit	integer	No	Number of results to return (default: 20)
offset	integer	No	Number of results to skip (default: 0)
sort	string	No	Sort field and direction, e.g. createdAt:desc

Response 200 OK

{
  "count": 28,
  "limit": 20,
  "offset": 0,
  "experiments": [
    {
      "id": "exp_abc123",
      "name": "Sentiment Analysis v2",
      "description": "Comparing transformer architectures for sentiment classification",
      "status": "running",
      "owner": "user_456",
      "organizationId": "org_xyz",
      "tags": ["nlp", "sentiment", "production"],
      "pinned": true,
      "runCount": 12,
      "bestRunId": "run_789",
      "isPublic": false,
      "createdAt": "2025-01-15T10:30:00Z",
      "updatedAt": "2025-02-01T14:22:00Z"
    }
  ]
}

---

POST /api/v1/experiments

Create a new experiment or run.

Scope: ml-workbench:write

Request Body

{
  "name": "Sentiment Analysis v2",
  "description": "Comparing transformer architectures for sentiment classification",
  "tags": ["nlp", "sentiment"],
  "run_id": "run_abc123",
  "experiment_name": "my-experiment",
  "run_name": "baseline-run",
  "parameters": { "learning_rate": 0.01, "epochs": 10 },
  "modelType": "classification",
  "problem_type": "binary",
  "framework": "sklearn",
  "parent_run_id": "run_parent_abc",
  "system_info": { "python_version": "3.11.0", "platform": "linux" }
}

Field	Type	Required	Description
name	string	Yes*	Experiment name
experiment_name	string	No	Alternative to name (used by AutoML trainer and SDK)
run_name	string	No	Alternative to name (falls back if name not provided)
description	string	No	Experiment description
tags	string[]	No	Array of tag strings for categorization
run_id	string	No	Custom run identifier
parameters	object or array	No	Hyperparameters (objects auto-converted to key-value arrays)
final_metrics	object or array	No	Final metrics (objects auto-converted to key-value arrays)
modelType	string	No	Model type (e.g., classification, regression)
problem_type	string	No	Problem type (e.g., binary, multiclass)
framework	string	No	ML framework (e.g., sklearn, pytorch)
parent_run_id	string	No	Parent run ID for nested runs
system_info	object	No	System information (Python version, platform, etc.)
status	string	No	Initial status (default: pending)
duration_seconds	number	No	Run duration in seconds

* If name is not provided, run_name or experiment_name will be used as the name.

Response 201 Created

{
  "id": "exp_abc123",
  "experiment_id": "exp_abc123",
  "run_id": "run_abc123",
  "name": "Sentiment Analysis v2",
  "status": "pending",
  "createdAt": "2025-01-15T10:30:00Z"
}

---

GET /api/v1/experiments/:id

Get a single experiment by ID.

Scope: ml-workbench:read

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment ID

Response 200 OK

Returns the full Experiment object.

---

PUT /api/v1/experiments/:id

Update an existing experiment or run.

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment ID

Request Body

{
  "name": "Sentiment Analysis v2 - Updated",
  "description": "Updated description with new findings",
  "status": "completed",
  "final_metrics": { "accuracy": 0.95, "f1_score": 0.92 },
  "error_message": "Optional error message if failed"
}

Field	Type	Required	Description
name	string	No	Experiment name
description	string	No	Experiment description
tags	string[]	No	Array of tag strings
status	string	No	New status (running, completed, failed)
final_metrics	object or array	No	Final metrics (objects auto-converted to key-value arrays)
duration_seconds	number	No	Run duration in seconds
error_message	string	No	Error message (when status is failed)

Response 200 OK

Returns the updated Experiment object.

---

DELETE /api/v1/experiments/:id

Delete an experiment and all associated runs. This action is irreversible.

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment ID

Response 204 No Content

---

POST /api/v1/experiments/:id/pin

Toggle the pinned status of an experiment. Pinned experiments appear at the top of list views for quick access.

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment ID

Response 200 OK

{
  "id": "exp_abc123",
  "pinned": true,
  "message": "Experiment pinned successfully"
}

---

PUT /api/v1/experiments/:id/tags

Replace the tags on an experiment. Overwrites the existing tag list.

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment ID

Request Body

{
  "tags": ["nlp", "sentiment", "production", "v2"]
}

Field	Type	Required	Description
tags	string[]	Yes	Array of tag strings to set on the experiment

Response 200 OK

{
  "id": "exp_abc123",
  "tags": ["nlp", "sentiment", "production", "v2"],
  "message": "Tags updated successfully"
}

---

GET /api/v1/experiments/compare

Compare two or more experiments side by side, including metrics and configuration differences.

Scope: ml-workbench:read

Query Parameters

Parameter	Type	Required	Description
ids	string	Yes	Comma-separated list of experiment IDs to compare (minimum 2)

Response 200 OK

{
  "experiments": [
    {
      "id": "exp_abc123",
      "name": "Sentiment Analysis v2",
      "status": "completed",
      "runCount": 12,
      "bestRunId": "run_789",
      "bestMetrics": {
        "accuracy": 0.934,
        "f1Score": 0.921,
        "loss": 0.187
      },
      "tags": ["nlp", "sentiment"],
      "createdAt": "2025-01-15T10:30:00Z"
    },
    {
      "id": "exp_def456",
      "name": "Sentiment Analysis v3",
      "status": "completed",
      "runCount": 8,
      "bestRunId": "run_012",
      "bestMetrics": {
        "accuracy": 0.951,
        "f1Score": 0.943,
        "loss": 0.142
      },
      "tags": ["nlp", "sentiment", "transformer"],
      "createdAt": "2025-01-22T09:15:00Z"
    }
  ]
}

---

GET /api/v1/experiments/stats

Get aggregate statistics for experiments in the organization.

Scope: ml-workbench:read

Response 200 OK

{
  "total": 28,
  "running": 3,
  "completed": 18,
  "failed": 5,
  "pinned": 7
}

---

Run Tracking Endpoints

These endpoints are used by the Python SDK and AutoML trainer to log metrics, parameters, and artifacts during training runs.

---

POST /api/v1/experiments/register

Register or find an experiment by name. If an experiment with the given name already exists for the authenticated user, returns it. Otherwise, creates a new one.

Scope: ml-workbench:write

Request Body

{
  "name": "my-classification-experiment",
  "description": "Optional description",
  "tags": ["nlp", "v2"]
}

Field	Type	Required	Description
name	string	Yes	Experiment name
description	string	No	Experiment description
tags	string[]	No	Array of tags

Response 200 OK (existing) or 201 Created (new)

{
  "experiment_id": "exp_abc123",
  "name": "my-classification-experiment",
  "exists": true
}

---

POST /api/v1/experiments/:id/metrics

Log metrics to an experiment run. Metrics are appended to the existing metrics array.

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment/run ID

Request Body

{
  "metrics": [
    { "key": "train_loss", "value": 0.25, "step": 5 },
    { "key": "val_loss", "value": 0.30, "step": 5 },
    { "key": "accuracy", "value": 0.92, "step": 5 }
  ]
}

Field	Type	Required	Description
metrics	array	Yes	Array of metric objects with key, value, and optional step/timestamp

Response 200 OK

{
  "logged": 3
}

---

POST /api/v1/experiments/:id/params

Log parameters to an experiment run. Parameters are merged with existing parameters (new keys added, existing keys updated).

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment/run ID

Request Body

{
  "params": {
    "learning_rate": 0.01,
    "batch_size": 32,
    "optimizer": "adam"
  }
}

Field	Type	Required	Description
params	object	Yes	Key-value pairs of parameters to log

Response 200 OK

{
  "logged": 3
}

---

POST /api/v1/experiments/:id/artifacts

Register or upload an artifact with an experiment run. Supports two modes:

1. Metadata registration — provide s3_key for an already-uploaded artifact
2. Direct upload — provide content_base64 to upload file content (SDK usage)

Scope: ml-workbench:write

Path Parameters

Parameter	Type	Required	Description
id	string	Yes	Experiment/run ID

Request Body

{
  "name": "model_weights.pkl",
  "path": "models/model_weights.pkl",
  "type": "model",
  "s3_key": "experiments/exp_abc123/artifacts/model_weights.pkl",
  "size": 1048576,
  "content_type": "application/octet-stream"
}

Or with direct upload:

{
  "name": "results.csv",
  "type": "file",
  "content_base64": "aWQsYWNjdXJhY3kKMSwwLjk1Cg==",
  "content_type": "text/csv"
}

Field	Type	Required	Description
name	string	Yes	Display name for the artifact
s3_key	string	No*	S3 key of an already-uploaded artifact
content_base64	string	No*	Base64-encoded file content for direct upload
path	string	No	Artifact path (defaults to name)
type	string	No	Artifact type: file, model, dataset, image (default: file)
size	integer	No	File size in bytes
content_type	string	No	MIME type

* Either s3_key or content_base64 must be provided.

Response 200 OK

{
  "artifact": {
    "name": "model_weights.pkl",
    "path": "models/model_weights.pkl",
    "type": "model",
    "s3_key": "experiments/exp_abc123/artifacts/model_weights.pkl",
    "size": 1048576,
    "content_type": "application/octet-stream",
    "created_at": "2025-01-15T12:00:00Z"
  }
}