Skip to main content
App version: 3.20250825

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
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.

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