Experiments API — Tracking, Metrics, and Comparison

The Experiments API stores the complete audit trail of every research run — parameters, metrics, artifact paths, MLflow run IDs, dataset version hashes, feature version hashes, model version hashes, and the Git commit at the time of the run. While the training and validation engines write Experiment rows automatically as a side-effect of calling the training endpoints, this API also exposes full CRUD so that external scripts, notebooks, or CI pipelines can register their own runs. The comparison endpoint drives the Experiment Tracker UI’s side-by-side view, computing a metric_diff structure that highlights the best-performing run per metric so researchers can immediately identify winning configurations.

Experiment CRUD

Create an Experiment Record

POST

string

/api/v1/experiments

Registers a new experiment run record. All version and lineage fields are optional so that records can be created incrementally — for example, writing parameters at dispatch time and then patching in metrics and mlflow_run_id once the run completes.

Request Body — `ExperimentCreate`

strategy_id

string (UUID)

required

UUID of the strategy this experiment belongs to. All experiments must be scoped to a strategy for the comparison and filtering queries to work correctly.

feature_version

string

Content hash (e.g. SHA-256 prefix) of the feature dataset version used in this run. Optional; populated automatically when triggered through the training endpoint.

model_version

string

Version identifier of the model artifact produced or used by this run.

dataset_version

string

Version hash of the training dataset assembly used in this run.

git_commit_hash

string

Git commit SHA at the time the run was dispatched, for full code-level reproducibility.

mlflow_run_id

string

MLflow run ID. If you use the platform’s training endpoints, this is set automatically from the MLflow client.

parameters

object

Free-form hyperparameter dict recorded at the time of the run. Defaults to {}.

metrics

object

Free-form metric results dict. Defaults to {}. Common keys: "mse", "mae", "directional_accuracy", "sharpe".

artifacts

object

Dictionary of artifact labels to S3 URIs, e.g. {"model": "s3://research-artifacts/models/MODEL_UUID/model.pkl", "feature_importance": "s3://..."}. Defaults to {}.

Response — `ExperimentRead`

string (UUID)

Unique experiment identifier.

strategy_id

string (UUID)

Parent strategy UUID.

feature_version

string | null

Feature dataset version hash.

model_version

string | null

Model artifact version.

dataset_version

string | null

Training dataset version hash.

git_commit_hash

string | null

Git commit SHA.

mlflow_run_id

string | null

MLflow run ID.

parameters

object

Recorded hyperparameters.

metrics

object

Recorded result metrics.

artifacts

object

Map of artifact labels to S3 URIs.

created_at

string (datetime)

ISO 8601 creation timestamp.

curl -X POST http://localhost:8000/api/v1/experiments \
  -H 'Content-Type: application/json' \
  -d '{
    "strategy_id": "STRATEGY_UUID",
    "mlflow_run_id": "abc123def456",
    "git_commit_hash": "f3a1b2c4d5e6",
    "parameters": {
      "n_estimators": 200,
      "max_depth": 5,
      "learning_rate": 0.05
    },
    "metrics": {
      "mse": 0.0023,
      "mae": 0.0341,
      "directional_accuracy": 0.54
    },
    "artifacts": {
      "model": "s3://research-artifacts/models/MODEL_UUID/model.pkl"
    }
  }'

List Experiments

GET

string

/api/v1/experiments

Returns a paginated list of experiment records, optionally filtered to a single strategy.

Query Parameters

strategy_id

string (UUID)

Filter results to experiments belonging to this strategy. If omitted, all experiments across all strategies are returned (subject to skip/limit).

skip

integer

Number of records to skip. Default 0.

limit

integer

Maximum records to return. Default 100.

Response: Array of ExperimentRead objects.

# All experiments for a strategy
curl "http://localhost:8000/api/v1/experiments?strategy_id=STRATEGY_UUID&skip=0&limit=20"

# All experiments (paginated)
curl "http://localhost:8000/api/v1/experiments?skip=0&limit=100"

Get an Experiment

GET

string

/api/v1/experiments/{experiment_id}

Fetches a single experiment record by UUID.

experiment_id

string (UUID)

required

UUID of the experiment to retrieve.

Response: ExperimentRead object. Errors: 404 Experiment not found.

curl http://localhost:8000/api/v1/experiments/EXP_UUID

Update an Experiment

PATCH

string

/api/v1/experiments/{experiment_id}

Partially updates an experiment record. Useful for back-filling metrics, mlflow_run_id, or artifacts after an async training job completes.

Request Body (all optional)

mlflow_run_id

string

Set or update the linked MLflow run ID.

parameters

object

Replace the stored parameters dict.

metrics

object

Replace the stored metrics dict.

artifacts

object

Replace the stored artifacts dict.

Response: Updated ExperimentRead object. Errors: 404 Experiment not found.

curl -X PATCH http://localhost:8000/api/v1/experiments/EXP_UUID \
  -H 'Content-Type: application/json' \
  -d '{
    "mlflow_run_id": "new_run_abc",
    "metrics": {"mse": 0.0019, "directional_accuracy": 0.57}
  }'

Delete an Experiment

DELETE

string

/api/v1/experiments/{experiment_id}

Permanently removes an experiment record from the database.

Deleting an experiment record does not delete the linked MLflow run or S3 artifacts. Those must be cleaned up independently through MLflow’s tracking API or your object-store management tooling.

Response: 204 No Content Errors: 404 Experiment not found.

curl -X DELETE http://localhost:8000/api/v1/experiments/EXP_UUID

Run Comparison

Compare Multiple Experiment Runs

POST

string

/api/v1/experiments/compare

Performs a side-by-side comparison of 2 to 10 experiment runs. Returns the full detail of each run alongside a metric_diff structure that, for every metric key present across any of the selected runs, lists the per-run values and identifies the best-performing run ID.

Request Body

A JSON array of experiment UUIDs (2–10 items).

["EXP_UUID_1", "EXP_UUID_2", "EXP_UUID_3"]

Response

experiments

array of objects

Full detail rows for each requested experiment, in the same order as the input IDs.

Show Experiment row fields

string

Experiment UUID.

strategy_id

string

Parent strategy UUID.

feature_version

string | null

Feature dataset version hash.

model_version

string | null

Model artifact version.

dataset_version

string | null

Training dataset version hash.

git_commit_hash

string | null

Git commit SHA.

mlflow_run_id

string | null

MLflow run ID.

parameters

object

Recorded hyperparameters.

metrics

object

Recorded result metrics.

artifacts

object

Artifact URI map.

created_at

string (datetime)

Run creation timestamp.

metric_diff

object

For each metric key found across any of the runs, provides the per-run values and the ID of the best-performing run.

Show metric_diff structure

{metric_key}.values

object

Map of experiment ID → metric value for this key. null if the run did not record that metric.

{metric_key}.best_id

string

UUID of the experiment with the lowest numeric value for this metric. null if no numeric values are present.

metric_diff.best_id is determined by selecting the experiment with the lowest numeric value for each metric. This is correct for error metrics such as MSE and MAE. For metrics where higher is better (e.g. directional_accuracy, sharpe), interpret best_id as the run with the smallest value — i.e. the field points at the minimum, so for maximization metrics you should select the run whose value is furthest from best_id.

Example response:

{
  "experiments": [
    {
      "id": "EXP_UUID_1",
      "strategy_id": "STRATEGY_UUID",
      "feature_version": "sha256:abc123",
      "model_version": "sha256:def456",
      "mlflow_run_id": "run_001",
      "parameters": {"n_estimators": 200, "max_depth": 5},
      "metrics": {"mse": 0.0023, "directional_accuracy": 0.54},
      "artifacts": {"model": "s3://research-artifacts/models/MODEL_UUID_1/model.pkl"},
      "created_at": "2024-01-15T10:30:00"
    },
    {
      "id": "EXP_UUID_2",
      "strategy_id": "STRATEGY_UUID",
      "feature_version": "sha256:abc123",
      "model_version": "sha256:ghi789",
      "mlflow_run_id": "run_002",
      "parameters": {"n_estimators": 400, "max_depth": 7},
      "metrics": {"mse": 0.0031, "directional_accuracy": 0.49},
      "artifacts": {"model": "s3://research-artifacts/models/MODEL_UUID_2/model.pkl"},
      "created_at": "2024-01-16T09:15:00"
    }
  ],
  "metric_diff": {
    "mse": {
      "values": {"EXP_UUID_1": 0.0023, "EXP_UUID_2": 0.0031},
      "best_id": "EXP_UUID_1"
    },
    "directional_accuracy": {
      "values": {"EXP_UUID_1": 0.54, "EXP_UUID_2": 0.49},
      "best_id": "EXP_UUID_2"
    }
  }
}

Errors:

400 Bad Request — if more than 10 UUIDs are supplied.
404 Not Found — if any of the supplied IDs does not exist in the database. The error detail lists the missing IDs.

curl -X POST http://localhost:8000/api/v1/experiments/compare \
  -H 'Content-Type: application/json' \
  -d '["EXP_UUID_1", "EXP_UUID_2", "EXP_UUID_3"]'

For per-run MLflow metric histories (step-level loss curves, epoch metrics) and full hyperparameter diffs with change highlighting, use the Tracking API at POST /api/v1/tracking/runs/compare. The Experiments API comparison endpoint is designed for high-level result comparison across strategy runs, while the Tracking API provides granular MLflow artifact introspection.

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Experiments API — Tracking, Metrics, and Comparison

Experiment CRUD

Create an Experiment Record

Request Body — `ExperimentCreate`

Response — `ExperimentRead`

List Experiments

Query Parameters

Get an Experiment

Update an Experiment

Request Body (all optional)

Delete an Experiment

Run Comparison

Compare Multiple Experiment Runs

Request Body

Response

Build docs developers (and LLMs) love

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Documentation Index

​Experiment CRUD

​Create an Experiment Record

​Request Body — ExperimentCreate

​Response — ExperimentRead

​List Experiments

​Query Parameters

​Get an Experiment

​Update an Experiment

​Request Body (all optional)

​Delete an Experiment

​Run Comparison

​Compare Multiple Experiment Runs

​Request Body

​Response

Build docs developers (and LLMs) love

Experiment CRUD

Create an Experiment Record

Request Body — `ExperimentCreate`

Response — `ExperimentRead`

List Experiments

Query Parameters

Get an Experiment

Update an Experiment

Request Body (all optional)

Delete an Experiment

Run Comparison

Compare Multiple Experiment Runs

Request Body

Response