Discovering data

Before you can ask for a metric or an attribute you need its exact name. The discovery RPCs answer “what is there?” at increasing levels of detail:

Question	RPC	Returns
Which attributes exist?	ListAttributesDefinitions, BrowseAttributesDefinitions	paths and types
Which metrics exist?	ListMetricDefinitions, BrowseMetricDefinitions	metric name, scale, label keys, value kind
Which series exist?	ListSeriesDefinitions	metric name, scale, full label values
Which values does a label take?	ListSeriesLabelValues	distinct values per key

Every discovery RPC pages with a resume token: limit is 1 to 10,000 (defaults are between 50 and 100), and a response carries resumeToken while more remain.

List or browse

Attribute paths and metric names use / as a hierarchy (config/optim/lr, train/loss). Each definition RPC comes in two forms:

• List returns every matching definition, flat — best for search and autocomplete.
• Browse returns one folder level: the sub-folders in directories plus the definitions directly inside. Pass directory ("" or "/" for the top level), then browse into a returned folder with "/a1".

Given the attributes a1/b1/c1, a1/b1/c2, a1/b2 and a2, browsing / returns the folder a1 and the attribute a2; browsing /a1 returns the folder b1 and the attribute b2.

Attribute definitions

ListAttributesDefinitions needs a source — which kind of resource to look at — and optionally narrows to one instance:

Source	Scope
projectSource	projects of the workspace, or one project
experimentSource	experiments of a project, or one experiment
directorySource	directories of a project, or one directoryPath
runSource	runs of a project, of one experiment, or one run

{
  "workspace": "my-workspace",
  "runSource": {"project": "vision"},
  "attrFilter": {"kinds": ["ATTR_KIND_FLOAT", "ATTR_KIND_INT"], "prefixPath": "config"},
  "limit": "1000"
}

attrFilter narrows by kind, and by name with one of all, regex (a regular expression over the full path) or prefixPath (children of a path). The browse form, BrowseAttributesDefinitions, takes a directory instead and filters by kind only.

Metric definitions

ListMetricDefinitions lists the metrics logged in a project — or in one experiment, or in the union of up to 1,000 runNames — with each one’s scale, label keys, value kind and whether it is an aggregated series:

{
  "workspace": "my-workspace",
  "project": "vision",
  "runNames": ["resnet50-lr3e-4", "resnet50-lr1e-4"],
  "metricNamePrefixes": ["train/", "eval/"],
  "valueKinds": ["SERIES_VALUE_KIND_FLOAT"],
  "skipAggregated": true
}

Narrow with metricNamePrefixes (any of), regex, scales (exact) and valueKinds. A metric logged with several value kinds, scales or label key sets appears once per combination. Reinforcement-learning series are listed separately, with the RL discovery RPCs.

Series definitions

ListSeriesDefinitions goes one level deeper: each concrete series, with its full label values, in a project, experiment or single run. Narrow it with series filters:

{
  "workspace": "my-workspace",
  "project": "vision",
  "run": "resnet50-lr3e-4",
  "seriesFilters": ["train/loss(filter=(gpu~=\"^[0-3]$\"))"]
}

Each result is a SeriesDefinition whose set member names its kind: regular, aggregated, histogram, densityHistogram, scatter or scatter3d. Scatter definitions carry their axis titles in metadataLabels.

Label values

ListSeriesLabelValues returns the distinct values of up to 10 label keys in one run, across all metrics — RL series included. Each key can be narrowed with valuePrefix or valueRegex:

{
  "workspace": "my-workspace",
  "project": "vision",
  "run": "resnet50-lr3e-4",
  "labelKeyFilters": [{"key": "gpu"}, {"key": "split", "valuePrefix": "val"}]
}

Reading attribute values

ListAttributes and BrowseAttributes return attribute values for a single project, experiment, directory or run, selected with the same kinds of source (each naming one instance):

{
  "workspace": "my-workspace",
  "runSource": {"project": "vision", "run": "resnet50-lr3e-4"},
  "attrFilter": {"prefixPath": "config"}
}

Each value is an Attribute whose set field gives its type: boolValue, stringValue, floatValue, intValue, stringSetValue or timestampValue.

To read a few known attributes for many runs at once, pass attributePaths to ListRuns instead.