Skip to main content
App version: 3.20250811

Neptune API

The Neptune API consists of two Python packages:

Related

Logging API​

For installation instructions, see Get started.

To import Neptune in your model-training code:

from neptune_scale import Run

Work with Run objects to create or resume experiments:

run = Run(...)

For instructions, see Log metadata.

caution

Neptune's worker process creation method requires the standard Python "main guard":

if __name__ == "__main__":
    # your Neptune code
    run = Run(...)

For details, see the Python documentation.

Query API​

Use the Query API to fetch and download logged metadata from your Neptune project.

Examples
import neptune_query as nq

# Use the extended syntax for any regular expression
nq.list_experiments(experiments=r"name_regex_1 & name_regex_2")

# Set the project directly in the function call (if different from NEPTUNE_PROJECT environment variable)
nq.list_experiments(project="your-project-path")

# Fetch configs and last logged loss of matching experiments
nq.fetch_experiments_table(
    project="company/my-other-project",
    experiments=r"name_regex_1 & !name_regex_2",  # AND NOT operator
    attributes=r"config | loss",
)

# Fetch last 10 values for each matching metric in specific experiment
nq.fetch_metrics(
    experiments=["specific-experiment-name"],
    attributes=r"^metrics/.*/regex$",
    tail_limit=10,
)
  • For setup and basic usage, see Query metadata.
  • For differences to the Fetcher API (neptune-fetcher), see the FAQ section below.

FAQ​

How does the Neptune client handle errors?

In case of metadata inconsistencies or other failures, you can control what happens by configuring the NEPTUNE_LOG_FAILURE_ACTION environment variable.

For more information, see Neptune API error handling.

Can we filter out Neptune warnings from our logs?

Yes, you can define a filter callback for Neptune-related warnings.

For instructions, see Filter out Neptune warnings from logs.

How can we migrate our logging code from legacy Neptune?

See the Neptune Python client 1.x migration guide.

What is the Neptune Query API and how is it different from the Fetcher API?

The new querying API is released as a separate package to ensure a more stable experience as we continue to improve and add functionality.

Usage of neptune-query is similar to neptune_fetcher.alpha, with the following differences:

  • You install and import from a different package.
  • Instead of using the Context class, you can pass a specific project path directly to the project argument of any fetching method.
  • Neptune's extended syntax is supported for regular expressions.
  • The methods for defining filters are simplified.
  • In filters, statistical aggregations are removed.

For detailed instructions, see Migrate from Fetcher Alpha to Query API.

What is the "old Fetcher API"?

The old Fetcher is the prototype API for Neptune 3.x, built around ReadOnlyRun and ReadOnlyProject. It's deprecated and we strongly recommend upgrading to the new Query API.

For instructions, see Migrate from old Fetcher to Query API.