fetch_metrics()

Python package: neptune-query

Fetches a table of metric values per step.

The values are raw, without any aggregation, approximation, or interpolation.

To narrow the results, limit the step range or the number of values from the tail end. You can also define filters for experiments to search or attributes to include.

Fetch experiment metrics

You can filter the results by:

• Experiments: Specify which experiments to search.
• Attributes: Only list attributes that match certain criteria.

Parameters

project

str

optional

default: None

Path of the Neptune project, as WorkspaceName/ProjectName.

If not provided, the NEPTUNE_PROJECT environment variable is used.

experiments

str | list[str] | Filter

required

Filter specifying which experiments to include.

• If a string is provided, it's treated as a regex pattern that the experiment names must match.
• If a list of strings is provided, it's treated as exact experiment names to match.
• To provide a more complex condition on an arbitrary attribute value, pass a Filter object.

If no filter is specified, all experiments are returned.

attributes

str | list[str] | AttributeFilter

required

Filter specifying which attributes to include.

• If a string is provided, it's treated as a regex pattern that the attribute names must match.
• If a list of strings is provided, it's treated as exact attribute names to match.
• To provide a more complex condition, pass an AttributeFilter object.

include_time

"absolute"

optional

default: None

Whether to include absolute timestamp. If set, each metric column has an additional sub-column with requested timestamp values.

step_range

Tuple[float | None, float | None]

optional

default: (None, None)

Tuple specifying the range of steps to include.

If None is used, it represents an open interval.

lineage_to_the_root

bool

optional

default: True

If True, includes all points from the complete experiment history.

If False, only includes points from the selected experiment.

tail_limit

int

optional

default: None

From the tail end of each series, how many points to include at most.

type_suffix_in_column_names

bool

optional

default: False

If True, columns of the returned DataFrame will be suffixed with ":<type>". For example: "attribute1:float_series", "attribute1:string".

If set to False, the method throws an exception if there are multiple types under one path.

include_point_previews

bool

optional

default: False

If set to True, metric previews are included in the returned DataFrame. The DataFrame will have additional sub-columns with preview information: is_preview and preview_completion.

Returns

pandas.DataFrame – A table of metric values per step. The DataFrame has a MultiIndex with:

• Index: ["experiment", "step"] for experiments or ["run", "step"] for runs
• Columns: attribute names with the following sub-columns:
  • "value" – metric values
  • "absolute_time" if the include_time argument is set to "absolute"
  • "is_preview" if the include_point_previews argument is set to True
  • "preview_completion" if the include_point_previews argument is set to True

Raises

• AttributeTypeInferenceError – If the attribute type wasn't specified in a filter passed to the experiments argument, and the attribute has multiple types across the project's experiments.
• ConflictingAttributeTypes – If there are conflicting attribute types under the same path and the type_suffix_in_column_names argument is set to False.

Examples

Fetch the last 12 values of a specific experiment's losses and accuracies, including incomplete points:

import neptune_query as nq


nq.fetch_metrics(
    experiments=["seabird-4"],
    attributes=r"loss | acc",
    tail_limit=12,
    include_point_previews=True,
)

Sample output

                  accuracy                                    loss
                is_preview preview_completion     value is_preview preview_completion     value
experiment step
seabird-4  37.0      False           1.000000  0.822683      False           1.000000  0.192384
           38.0      False           1.000000  0.821014      False           1.000000  0.200655
           39.0      False           1.000000  0.800180      False           1.000000  0.181736
           41.0       True           0.756098  0.813834       True           0.756098  0.178080
           42.0       True           0.761905  0.802206       True           0.761905  0.178129
           43.0       True           0.767442  0.822235       True           0.767442  0.192478
           44.0       True           0.772727  0.809570       True           0.772727  0.192476
           45.0       True           0.777778  0.817433       True           0.777778  0.191994
           46.0       True           0.782609  0.802809       True           0.782609  0.186171
           47.0       True           0.787234  0.803025       True           0.787234  0.196133
           48.0       True           0.791667  0.820802       True           0.791667  0.188257
           49.0       True           0.795918  0.821936       True           0.795918  0.182162

Fetch the last 15 values of a specific experiment's losses, including all extra information:

nq.fetch_metrics(
    experiments=["seabird-4"],
    attributes=r"loss",
    tail_limit=15,
    include_time="absolute",
    type_suffix_in_column_names=True,
    include_point_previews=True,
)

Sample output

                               loss:float_series
                                   absolute_time is_preview preview_completion     value
experiment step
seabird-4  34.0 2025-08-29 09:18:27.875000+00:00      False           1.000000  0.184275
           35.0 2025-08-29 09:18:27.884000+00:00      False           1.000000  0.191002
           36.0 2025-08-29 09:18:27.888000+00:00      False           1.000000  0.197030
           37.0 2025-08-29 09:18:27.891000+00:00      False           1.000000  0.192384
           38.0 2025-08-29 09:18:27.895000+00:00      False           1.000000  0.200655
           39.0 2025-08-29 09:18:27.899000+00:00      False           1.000000  0.181736
           41.0 2025-08-29 09:18:27.902000+00:00       True           0.756098  0.178080
           42.0 2025-08-29 09:18:27.902000+00:00       True           0.761905  0.178129
           43.0 2025-08-29 09:18:27.916000+00:00       True           0.767442  0.192478
           44.0 2025-08-29 09:18:27.920000+00:00       True           0.772727  0.192476
           45.0 2025-08-29 09:18:27.925000+00:00       True           0.777778  0.191994
           46.0 2025-08-29 09:18:27.929000+00:00       True           0.782609  0.186171
           47.0 2025-08-29 09:18:27.934000+00:00       True           0.787234  0.196133
           48.0 2025-08-29 09:18:27.934000+00:00       True           0.791667  0.188257
           49.0 2025-08-29 09:18:27.942000+00:00       True           0.795918  0.182162

Fetch from runs

To target individual runs by ID instead of experiment name, import the runs API:

import neptune_query.runs as nq_runs

Then call the corresponding querying method and replace the experiments parameter with runs:

nq_runs.fetch_metrics(
    runs=["prompt-wolf-20250605132116671-2g2r1"],  # run ID
    attributes=r"^loss/.*",
    step_range=(1000.0, None),
    include_point_previews=True,
)