Skip to main content

How to Find the Child Runs of a Parent Run in MLflow

· 5 min read
Jagdish Kumawat
Founder @ Dewiride

Every child run carries a tag, mlflow.parentRunId, holding its parent's run ID. That makes a parent's children one search away: filter the experiment's runs on that tag. This guide finds the children of a nightly batch of models and ranks them by loss, with real output from MLflow 3.18.0.

Syntax​

Syntax
children = mlflow.search_runs(
experiment_names=["<experiment>"],
filter_string=f"tags.mlflow.parentRunId = '{parent_run_id}'",
)
PartWhat it means
tags.mlflow.parentRunIdThe tag MLflow puts on every child run
'{parent_run_id}'The parent's run ID, in single quotes: tag values are text
experiment_names=[...]Where to search. Children are in their parent's experiment

Add order_by=["metrics.<metric> ASC"] to sort them; How to Search MLflow Runs in Python with search_runs covers the rest of search_runs.

Prerequisites​

Step 1: Create a Parent with Three Children​

The example is a nightly batch that trains three models, each a child run with its loss. Create make_batch.py:

make_batch.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")
mlflow.set_experiment("child-runs-demo")

with mlflow.start_run(run_name="nightly-batch"):
for name, loss in [("model-a", 0.42), ("model-b", 0.37), ("model-c", 0.51)]:
with mlflow.start_run(run_name=name, nested=True):
mlflow.log_metric("loss", loss)
Terminal
uv run python make_batch.py

It prints a View run link for each of the three children, then one for nightly-batch.

Step 2: Find the Children​

The script first finds the parent by its name, to get its run ID, then searches for the runs whose mlflow.parentRunId is that ID, lowest loss first. Create find_children.py:

The find_children.py script in a macOS-style code window: it finds the run named nightly-batch in child-runs-demo as a list, then searches the same experiment with the filter tags.mlflow.parentRunId equal to the parent's run ID, ordered by metrics.loss ascending, and prints the run name and loss columns.

find_children.py
import mlflow

mlflow.set_tracking_uri("http://127.0.0.1:8080")

parent = mlflow.search_runs(
experiment_names=["child-runs-demo"],
filter_string="attributes.run_name = 'nightly-batch'",
output_format="list",
)[0]

children = mlflow.search_runs(
experiment_names=["child-runs-demo"],
filter_string=f"tags.mlflow.parentRunId = '{parent.info.run_id}'",
order_by=["metrics.loss ASC"],
)
print(children[["tags.mlflow.runName", "metrics.loss"]].to_string(index=False))
Terminal
uv run python find_children.py
Output
tags.mlflow.runName metrics.loss
model-b 0.37
model-a 0.42
model-c 0.51

A terminal running uv run python find_children.py: a table of the three children, model-b with loss 0.37, model-a with 0.42 and model-c with 0.51.

All three children came back, best first: model-b. The parent isn't in the list, since it has no mlflow.parentRunId tag of its own. How to Find an MLflow Run by Name explains the first search.

Common Mistakes​

MistakeWhat happensDo this instead
Leaving out the quotes around the IDRestException: INVALID_PARAMETER_VALUE: Invalid clause(s) in filter string: 'tags.mlflow.parentRunId = 2343badc...'Put the ID in single quotes
Searching another experimentAn empty result, with no errorSearch the parent's experiment
Using the parent's name instead of its IDNo child matches: the tag holds the IDLook the ID up first, as in Step 2

Troubleshooting​

SymptomLikely causeFix
The result is emptyWrong experiment, or the parent has no childrenCheck the parent's page: its Child runs row lists them
Invalid clause(s) in filter stringMissing quotes, or a typo in tags.mlflow.parentRunIdCopy the filter from the Syntax section

FAQ​

Can I get only the best child?​

Add max_results=1 and output_format="list", and take [0]: How to Find the Best Run in MLflow.

Does this work for autologged searches?​

Yes: the child runs of an autologged GridSearchCV carry the same tag, so order_by=["metrics.mean_test_score DESC"] ranks the candidates.

Can the UI do the same?​

Yes, the runs table folds children under their parent: How to See Nested Runs in the MLflow UI.

Conclusion​

filter_string=f"tags.mlflow.parentRunId = '{parent.info.run_id}'" returned the three children of nightly-batch, ranked by loss. Quote the ID, search the parent's experiment, and look the ID up by name when you only know the parent's name.

Additional Resources​