Experiment Tracking API — MLflow Run Management and Search

The Experiment Tracking API provides a platform-specific façade over the underlying MLflow tracking server. Rather than coupling the frontend or downstream tools directly to MLflow’s native API contract, all interactions are routed through this layer so the platform can apply consistent filtering, pagination, and enrichment. Every training run, walk-forward fold, CPCV iteration, and backtest execution is logged here with full lineage tags — including strategy_id, run_type, git_commit, dataset_version, feature_version, and model_version — making it straightforward to trace any model artefact back to the exact research session that produced it.

Runs

List and Search Runs

GET

endpoint

/api/v1/tracking/runs

Searches MLflow runs in the default experiment, with optional tag-based filters for run_type and strategy_id. Results are ordered by start_time DESC. Use this endpoint to quickly surface all runs associated with a particular strategy or pipeline stage.

Query Parameters

run_type

string

Filter by the run_type MLflow tag (e.g. "training", "walk_forward", "cpcv", "backtest"). Translated to the MLflow filter expression tags.run_type = '<value>'.

strategy_id

string

Filter by the strategy_id MLflow tag (UUID string). Translated to tags.strategy_id = '<value>'. Combine with run_type to retrieve only the backtest runs for a specific strategy.

limit

integer

default:"50"

Maximum number of runs to return. The underlying MLflow search caps at 100; values above 100 are silently clamped.

Response

runs

list[object]

List of run summary objects, each containing run_id, run_name, status, start_time, params, metrics, and tags.

total

integer

Count of runs returned (equal to the length of the runs list).

# Retrieve all walk-forward runs for a specific strategy
curl "https://api.example.com/api/v1/tracking/runs?run_type=walk_forward&strategy_id=a1b2c3d4-e5f6-7890-abcd-ef1234567890&limit=20"

{
  "runs": [
    {
      "run_id": "abc123def456",
      "run_name": "walk_forward",
      "status": "FINISHED",
      "start_time": 1699900800000,
      "params": { "n_splits": "5", "method": "rolling" },
      "metrics": { "mean_oos_sharpe": 1.42, "std_oos_sharpe": 0.31 },
      "tags": {
        "run_type": "walk_forward",
        "strategy_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
        "git_commit": "3f9a1c2"
      }
    }
  ],
  "total": 1
}

Get Run Detail

GET

endpoint

/api/v1/tracking/runs/{run_id}

Returns full metadata for a single MLflow run including all logged parameters, final metric values, and all tags. The /metrics sub-resource exposes the same final metric values as a dedicated response.

Path Parameters

run_id

string

required

The MLflow run ID string (e.g. "abc123def456").

Response

run_id

string

MLflow run identifier.

run_name

string

Human-readable run name set at creation time (typically the run_type value).

status

string

MLflow run status: RUNNING, SCHEDULED, FINISHED, FAILED, or KILLED.

start_time

integer

Unix epoch milliseconds when the run started.

end_time

integer

Unix epoch milliseconds when the run ended. null if the run is still active.

artifact_uri

string

Root URI for this run’s artifacts in the configured artifact store (local path, S3, or MinIO).

params

object

Dictionary of logged hyperparameters (string keys and string values as stored by MLflow).

metrics

object

Dictionary of final metric values (string key → float).

Get Run Metrics

GET

endpoint

/api/v1/tracking/runs/{run_id}/metrics

Returns the final logged metric values for every metric recorded against a run. Values are sourced directly from run.data.metrics via the get_run_metrics client function, which returns a flat dictionary of metric name to final float value. Returns an empty metrics object if the run is not found.

Path Parameters

run_id

string

required

The MLflow run ID.

Response

run_id

string

The run identifier echoed back.

metrics

object

Flat dictionary of metric name → final float value as stored in run.data.metrics. Returns an empty object {} if the run does not exist.

curl https://api.example.com/api/v1/tracking/runs/abc123def456/metrics

{
  "run_id": "abc123def456",
  "metrics": {
    "oos_sharpe": 1.42,
    "oos_sortino": 1.87,
    "max_drawdown": -0.1231,
    "calmar_ratio": 1.15
  }
}

Get Run Hyperparameters

GET

endpoint

/api/v1/tracking/runs/{run_id}/params

Returns only the logged hyperparameters for a run, without metrics or tags. Useful for lightweight lookups when building comparison tables or audit trails without pulling the full run record.

Path Parameters

run_id

string

required

The MLflow run ID.

Response

run_id

string

The run identifier echoed back.

params

object

Flat dictionary of all hyperparameters logged to this run (string keys and string values, as MLflow stores them). Returns an empty object {} if the run is not found.

curl https://api.example.com/api/v1/tracking/runs/abc123def456/params

{
  "run_id": "abc123def456",
  "params": {
    "plugin_key": "ml.xgboost",
    "max_depth": "6",
    "learning_rate": "0.05",
    "n_estimators": "200",
    "subsample": "0.8",
    "colsample_bytree": "0.8"
  }
}

Compare Runs

POST

endpoint

/api/v1/tracking/runs/compare

Performs a side-by-side diff of metrics and hyperparameters across 2–10 MLflow runs. The response highlights the best-performing run per metric and flags which hyperparameters differ across the comparison set, making it straightforward to identify which configuration changes drove performance improvements or regressions.

The param_diff object includes a varies boolean for each hyperparameter key. When varies is true, that parameter took different values across the compared runs — these are the parameters most worth investigating as the source of performance differences. Parameters with varies: false were held constant and can be ignored in the comparison.

Request Body

run_ids

list[string]

required

List of 2 to 10 MLflow run ID strings to compare. All runs must exist; a 404 is returned if any ID is not found.

Response

runs

list[object]

Ordered list of run summaries (one per requested run_id), each containing run_id, run_name, run_type, params, and metrics.

metric_diff

object

Dictionary keyed by metric name.

Show metric_diff entry fields

values

object

Map of run_id → metric_value for this metric across all compared runs. null if the run did not log this metric.

best_run_id

string

The run_id that achieved the highest numeric value for this metric. null if no numeric values are available.

param_diff

object

Dictionary keyed by hyperparameter name.

Show param_diff entry fields

values

object

Map of run_id → param_value for this parameter across all compared runs. null if the run did not log this parameter.

varies

boolean

true if this parameter took different string values across at least two of the compared runs. Use this to quickly identify which hyperparameters were actually changed between runs.

curl -X POST https://api.example.com/api/v1/tracking/runs/compare \
  -H "Content-Type: application/json" \
  -d '{
    "run_ids": [
      "abc123def456",
      "def456ghi789",
      "ghi789jkl012"
    ]
  }'

{
  "runs": [
    {
      "run_id": "abc123def456",
      "run_name": "training",
      "run_type": "training",
      "params": { "learning_rate": "0.05", "max_depth": "6", "n_estimators": "200" },
      "metrics": { "oos_sharpe": 1.42, "max_drawdown": -0.1231 }
    },
    {
      "run_id": "def456ghi789",
      "run_name": "training",
      "run_type": "training",
      "params": { "learning_rate": "0.01", "max_depth": "6", "n_estimators": "200" },
      "metrics": { "oos_sharpe": 1.18, "max_drawdown": -0.1544 }
    },
    {
      "run_id": "ghi789jkl012",
      "run_name": "training",
      "run_type": "training",
      "params": { "learning_rate": "0.10", "max_depth": "8", "n_estimators": "300" },
      "metrics": { "oos_sharpe": 1.35, "max_drawdown": -0.1389 }
    }
  ],
  "metric_diff": {
    "oos_sharpe": {
      "values": {
        "abc123def456": 1.42,
        "def456ghi789": 1.18,
        "ghi789jkl012": 1.35
      },
      "best_run_id": "abc123def456"
    },
    "max_drawdown": {
      "values": {
        "abc123def456": -0.1231,
        "def456ghi789": -0.1544,
        "ghi789jkl012": -0.1389
      },
      "best_run_id": "abc123def456"
    }
  },
  "param_diff": {
    "learning_rate": {
      "values": {
        "abc123def456": "0.05",
        "def456ghi789": "0.01",
        "ghi789jkl012": "0.10"
      },
      "varies": true
    },
    "max_depth": {
      "values": {
        "abc123def456": "6",
        "def456ghi789": "6",
        "ghi789jkl012": "8"
      },
      "varies": true
    },
    "n_estimators": {
      "values": {
        "abc123def456": "200",
        "def456ghi789": "200",
        "ghi789jkl012": "300"
      },
      "varies": true
    }
  }
}

Experiments

List MLflow Experiments

GET

endpoint

/api/v1/tracking/experiments

Lists all MLflow experiments registered in the configured tracking server. The platform typically creates one experiment per MLFLOW_EXPERIMENT_NAME setting at startup, but additional experiments may exist if multiple environments share the same tracking server or if experiments were created manually.

Copy an experiment_id from this response and paste it into the MLflow UI’s experiment filter to scope the run table to only runs from that experiment. This is particularly useful when multiple strategies or environments share a single MLflow server.

Response

experiments

list[object]

List of experiment records.

Show Experiment fields

experiment_id

string

MLflow experiment identifier string (e.g. "1", "2").

name

string

Human-readable experiment name as set by MLFLOW_EXPERIMENT_NAME in the platform configuration.

artifact_location

string

Root URI for all artifacts logged to runs within this experiment (local filesystem path, s3://, or mlflow-artifacts:// scheme).

lifecycle_stage

string

MLflow lifecycle stage: "active" or "deleted".

curl https://api.example.com/api/v1/tracking/experiments

{
  "experiments": [
    {
      "experiment_id": "0",
      "name": "Default",
      "artifact_location": "mlflow-artifacts:/0",
      "lifecycle_stage": "active"
    },
    {
      "experiment_id": "1",
      "name": "hedge-fund-research",
      "artifact_location": "s3://mlflow-artifacts/1",
      "lifecycle_stage": "active"
    }
  ]
}

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Experiment Tracking API — MLflow Run Management and Search

Runs

List and Search Runs

Query Parameters

Response

Get Run Detail

Path Parameters

Response

Get Run Metrics

Path Parameters

Response

Get Run Hyperparameters

Path Parameters

Response

Compare Runs

Request Body

Response

Experiments

List MLflow Experiments

Response

Build docs developers (and LLMs) love

Strategies

Features & Models

Backtesting & Validation

Intelligence & Tracking

Documentation Index

​Runs

​List and Search Runs

​Query Parameters

​Response

​Get Run Detail

​Path Parameters

​Response

​Get Run Metrics

​Path Parameters

​Response

​Get Run Hyperparameters

​Path Parameters

​Response

​Compare Runs

​Request Body

​Response

​Experiments

​List MLflow Experiments

​Response

Build docs developers (and LLMs) love

Runs

List and Search Runs

Query Parameters

Response

Get Run Detail

Path Parameters

Response

Get Run Metrics

Path Parameters

Response

Get Run Hyperparameters

Path Parameters

Response

Compare Runs

Request Body

Response

Experiments

List MLflow Experiments

Response