Skip to main content
App version: 3.20250908

fetch_series()

Python package: neptune-query

Fetches a table of series values per step, for non-numerical series attributes.

To narrow the results, define filters for experiments to search or attributes to include.

Supported types:

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

Returns​

pandas.DataFrame – A table of series values per step for non-numerical series. The DataFrame has a MultiIndex with:

  • Index: ["experiment", "step"] for experiments or ["run", "step"] for runs
  • Columns:
    • "value" – File objects, strings, or histograms
    • "absolute_time" if the include_time argument is set to "absolute"

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.

Example​

Fetch file series of two specific experiments from step 1 to 3 and include the absolute timestamp:

import neptune_query as nq


nq.fetch_series(
    experiments=["seabird-4", "seabird-5"],
    attributes=r"^predictions/",
    step_range=(1.0, 3.0),
    include_time="absolute",
)
Sample output
                                     predictions
                                   absolute_time                                     value
experiment step
seabird-4  1.0  2025-08-29 09:18:27.946000+00:00  File(size=24.89 KB, mime_type=image/png)
           2.0  2025-08-29 09:18:29.949000+00:00  File(size=26.66 KB, mime_type=image/png)
           3.0  2025-08-29 09:19:01.952000+00:00   File(size=6.89 KB, mime_type=image/png)
seabird-5  1.0  2025-08-29 09:21:07.946000+00:00  File(size=23.66 KB, mime_type=image/png)
           2.0  2025-08-29 09:22:25.949000+00:00  File(size=25.43 KB, mime_type=image/png)
           3.0  2025-08-29 09:24:27.952000+00:00   File(size=6.58 KB, mime_type=image/png)

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_series(
    runs=["prompt-wolf-20250605132116671-2g2r1"],  # run ID
    attributes=r"^messages/",
    step_range=(1000.0, None),
)