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 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.

Scope: ml-workbench:write

Request Body

{
  "name": "Sentiment Analysis v2",
  "description": "Comparing transformer architectures for sentiment classification",
  "tags": ["nlp", "sentiment"]
}

Field	Type	Required	Description
name	string	Yes	Experiment name
description	string	No	Experiment description
tags	string[]	No	Array of tag strings for categorization

Response 201 Created

{
  "id": "exp_abc123",
  "name": "Sentiment Analysis v2",
  "status": "draft",
  "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.

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",
  "tags": ["nlp", "sentiment", "production"]
}

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

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
}