fetch_metrics()

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

optional

default: None

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

optional

default: None

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]

required

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.

Example

Fetch losses of two specific experiments from step 1000 onward, including incomplete points:

import neptune_query as nq


nq.fetch_metrics(
    experiments=["seagull-week1", "seagull-week2"],
    attributes=r"^loss/.*",
    step_range=(1000.0, None),
    include_point_previews=True,
)

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,
)