Skip to content
Metrana Docs

Discovery

ListAttributesDefinitions

Section titled “ListAttributesDefinitions”

Discovers attribute definitions used by a specific resource type (projects, experiments, directories, or runs).

ListAttributesDefinitionsRequest

Section titled “ListAttributesDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project_source projectSource AttrDefProjectSource
oneof source
directory_source directorySource AttrDefDirectorySource
oneof source
experiment_source experimentSource AttrDefExperimentSource
oneof source
run_source runSource AttrDefRunSource
oneof source
attr_filter attrFilter ListAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params like source must be still included in the request.

ListAttributesDefinitionsResponse

Section titled “ListAttributesDefinitionsResponse”
Field JSON Type Description
attribute_defs attributeDefs repeated AttributeDef
resume_token resumeToken optional string Optional resume token if more results are there

BrowseAttributesDefinitions

Section titled “BrowseAttributesDefinitions”

Discovers attribute definitions used by a specific resource type (projects, experiments, directories, or runs) within a single attribute directory. Works like ListAttributeDefinitions but scoped to one directory level. For example, suppose the following attributes exist:

  • a1/b1/c1

  • a1/b1/c2

  • a1/b1/c3

  • a1/b2

  • a2 If user picks up “/”, response will contain “a1” as a directory and “a2” as an attribute. If user asks for “/a1”, response will contain “b1” as a directory and “b2” as an attribute.

  • gRPC: /metrana_protobuf.query.v1.svc.QueryService/BrowseAttributesDefinitions (unary)

  • REST: POST /api/query/v1/attributes-definitions:browse

  • Request: BrowseAttributesDefinitionsRequest

  • Response: BrowseAttributesDefinitionsResponse

BrowseAttributesDefinitionsRequest

Section titled “BrowseAttributesDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
directory directory string Directory to fetch attribute definitions from. Empty string and “/” are treated equally and interpreted as fetching from root directory only.
project_source projectSource AttrDefProjectSource
oneof source
directory_source directorySource AttrDefDirectorySource
oneof source
experiment_source experimentSource AttrDefExperimentSource
oneof source
run_source runSource AttrDefRunSource
oneof source
attr_filter attrFilter BrowseAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified. Limit includes directories too.
resume_token resumeToken optional string If specified, resumes from last request. Other params like source must be still included in the request.

BrowseAttributesDefinitionsResponse

Section titled “BrowseAttributesDefinitionsResponse”
Field JSON Type Description
directories directories repeated string
attribute_defs attributeDefs repeated AttributeDef
resume_token resumeToken optional string Optional resume token if more results are there

ListRLAttributesDefinitions

Section titled “ListRLAttributesDefinitions”

Discovers RL environment attribute definitions used within a run. Works like ListAttributesDefinitions, but the source is always a specific run (mandatory project + run), optionally narrowed to a single environment.

ListRLAttributesDefinitionsRequest

Section titled “ListRLAttributesDefinitionsRequest”

RL env attribute definitions are sourced from a single run (no oneof source), optionally narrowed to one environment.

Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run string
environment environment optional string If set, discover attributes of this environment only. If unset, discover across all environments in the run.
attr_filter attrFilter ListAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params like source must be still included in the request.

ListRLAttributesDefinitionsResponse

Section titled “ListRLAttributesDefinitionsResponse”
Field JSON Type Description
attribute_defs attributeDefs repeated AttributeDef
resume_token resumeToken optional string Optional resume token if more results are there

ListRLAttributesDefinitionsAcrossRuns

Section titled “ListRLAttributesDefinitionsAcrossRuns”

Discovers RL environment attribute definitions across multiple runs: the deduplicated union over all environments of every requested run. Unlike ListRLAttributesDefinitions there is no environment scoping, by design — environment ids are not comparable across runs.

ListRLAttributesDefinitionsAcrossRunsRequest

Section titled “ListRLAttributesDefinitionsAcrossRunsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
runs runs repeated string Runs to discover in — returns attribute definitions present in at least one environment of at least one of these runs, deduplicated. At least 1 and at most 100 runs; duplicate names are deduplicated.
attr_filter attrFilter ListAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params like source must be still included in the request.

BrowseRLAttributesDefinitions

Section titled “BrowseRLAttributesDefinitions”

Browses RL environment attribute definitions within a run, scoped to a single attribute directory level (see BrowseAttributesDefinitions for the tree example). The source is always a specific run (mandatory project + run), optionally narrowed to a single environment.

BrowseRLAttributesDefinitionsRequest

Section titled “BrowseRLAttributesDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run string
environment environment optional string If set, browse attributes of this environment only. If unset, browse across all environments in the run.
directory directory string Directory to fetch attribute definitions from. Empty string and “/” are treated equally and interpreted as fetching from root directory only.
attr_filter attrFilter BrowseAttrFilter Controls which attributes are included in the response. If unset, all attributes are returned.
limit limit optional int64 How many attributes to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified. Limit includes directories too.
resume_token resumeToken optional string If specified, resumes from last request. Other params like source must be still included in the request.

BrowseRLAttributesDefinitionsResponse

Section titled “BrowseRLAttributesDefinitionsResponse”
Field JSON Type Description
directories directories repeated string
attribute_defs attributeDefs repeated AttributeDef
resume_token resumeToken optional string Optional resume token if more results are there

ListMetricDefinitions

Section titled “ListMetricDefinitions”

Discovers metric definitions (regular and aggregated) within a project. Optionally scoped to an experiment/run. It allows discovering metric, scale names, and label keys they use. They dont show label values. It does not contain RL specific metric definitions.

ListMetricDefinitionsRequest

Section titled “ListMetricDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
experiment experiment optional string If set, scopes to runs belonging to this experiment.
run run optional string Deprecated. DEPRECATED: Use run_names instead. Treated as a single-element run_names if run_names is empty, ignored otherwise.
run_names runNames repeated string If not empty, scopes to the union of these runs — returns metric definitions present in at least one of them, deduplicated. At most 1000 runs may be requested. If any run is given, experiment field is ignored.
metric_name_prefixes metricNamePrefixes repeated string Optional list. If not present, response includes all combinations of metric definitions. Otherwise, returns metrics whose names match at least one prefix.
regex regex optional string Optional regex to apply on all metric names. This filter is combined with metric name prefixes (if specified), Metric name must satisfy both regex and one of metric name prefixes.
scales scales repeated string Optional list. If not present, response includes all existing scale names combined with metric names. Otherwise, response contains only metric definitions whose scales match one of specified ones fully.
skip_aggregated skipAggregated bool If true, aggregated metric definitions are excluded from the response.
value_kinds valueKinds repeated SeriesValueKind Optional list. If not empty, only metric definitions of these value kinds are returned. If empty, all value kinds are included.
limit limit optional int64 How many definitions to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params like metric name prefixes (if given originally) must be still included in the request.

ListMetricDefinitionsResponse

Section titled “ListMetricDefinitionsResponse”
Field JSON Type Description
metric_definitions metricDefinitions repeated MetricDefinition
resume_token resumeToken optional string Optional resume token if more results are there

BrowseMetricDefinitions

Section titled “BrowseMetricDefinitions”

Discovers metric definitions (regular and aggregated) within a project and directory, optionally scoped to an experiment/run. It works in similar way as ListMetricDefinitions, but it works on directory level - user needs to specify directory in the request, and response does show only contents for current directory. For example, suppose the following metric names exist:

  • a1/b1/c1

  • a1/b1/c2

  • a1/b1/c3

  • a1/b2

  • a2 If user picks up “/”, response will contain “a1” as a directory and “a2” as a metric name. If user asks for “/a1”, response will contain “b1” as a directory and “b2” as a metric name. It does not contain RL specific metric definitions.

  • gRPC: /metrana_protobuf.query.v1.svc.QueryService/BrowseMetricDefinitions (unary)

  • REST: POST /api/query/v1/metric-definitions:browse

  • Request: BrowseMetricDefinitionsRequest

  • Response: BrowseMetricDefinitionsResponse

BrowseMetricDefinitionsRequest

Section titled “BrowseMetricDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
directory directory string Directory to fetch metric definitions from. Empty string and “/” are treated equally and interpreted as fetching from root directory only.
experiment experiment optional string If set, scopes to runs belonging to this experiment.
run run optional string Deprecated. DEPRECATED: Use run_names instead. Treated as a single-element run_names if run_names is empty, ignored otherwise.
run_names runNames repeated string If not empty, scopes to the union of these runs — returns directories and metric definitions present in at least one of them, deduplicated. At most 1000 runs may be requested. If any run is given, experiment field is ignored.
regex regex optional string Optional regex to apply on all metric and directory names. This regex filter is applied to part of metric name AFTER directory stripped.
skip_aggregated skipAggregated bool If true, aggregated metric definitions are excluded from the response. Directories are not affected by this filter.
value_kinds valueKinds repeated SeriesValueKind Optional list. If not empty, only metric definitions of these value kinds are returned. If empty, all value kinds are included. Directories are not affected by this filter.
limit limit optional int64 How many definitions to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified. Limit is counted towards both directories and metric definitions all together.
resume_token resumeToken optional string If specified, resumes from last request. Other params (directory, experiment, run) must be kept the same.

BrowseMetricDefinitionsResponse

Section titled “BrowseMetricDefinitionsResponse”
Field JSON Type Description
directories directories repeated string List of further directories where next metric definitions may be.
metric_definitions metricDefinitions repeated MetricDefinition List of metric definitions in current directory
resume_token resumeToken optional string Optional resume token if more results are there

ListRLEnvironmentMetricDefinitions

Section titled “ListRLEnvironmentMetricDefinitions”

Discovers full series definitions inside a run for those series which belong to a RL environment. Optional environment here allows discovering metrics for environments in general.

ListRLEnvironmentMetricDefinitionsRequest

Section titled “ListRLEnvironmentMetricDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run string
environment environment optional string Deprecated. DEPRECATED: Use environments instead. Treated as a single-element environments if environments is empty, ignored otherwise.
environments environments repeated string If not empty, scopes to the union of these environments — returns metric definitions present in at least one of them, deduplicated. If empty (and environment is unset), returns the union across all environments. At most 1000 environments may be requested.
metric_name_prefixes metricNamePrefixes repeated string Optional list. If not present, response includes all combinations of metric definitions. Otherwise, returns metrics whose names match at least one prefix.
regex regex optional string Optional regex to apply on all metric names. This filter is combined with metric name prefixes (if specified). Metric name must satisfy both regex and one of metric name prefixes.
scales scales repeated string Optional list. If not present, response includes all existing scale names combined with metric names. Otherwise, response contains only metric definitions whose scales match one of specified ones fully.
limit limit optional int64
resume_token resumeToken optional string

ListRLEnvironmentMetricDefinitionsAcrossRuns

Section titled “ListRLEnvironmentMetricDefinitionsAcrossRuns”

Discovers RL environment metric definitions across multiple runs: the deduplicated union over all environments of every requested run. Unlike ListRLEnvironmentMetricDefinitions there is no environment scoping, by design — environment ids are not comparable across runs.

ListRLEnvironmentMetricDefinitionsAcrossRunsRequest

Section titled “ListRLEnvironmentMetricDefinitionsAcrossRunsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
runs runs repeated string Runs to discover in — returns metric definitions present in at least one environment of at least one of these runs, deduplicated. At least 1 and at most 100 runs; duplicate names are deduplicated.
metric_name_prefixes metricNamePrefixes repeated string Optional list. If not present, response includes all combinations of metric definitions. Otherwise, returns metrics whose names match at least one prefix.
regex regex optional string Optional regex to apply on all metric names. This filter is combined with metric name prefixes (if specified). Metric name must satisfy both regex and one of metric name prefixes.
scales scales repeated string Optional list. If not present, response includes all existing scale names combined with metric names. Otherwise, response contains only metric definitions whose scales match one of specified ones fully.
limit limit optional int64
resume_token resumeToken optional string

BrowseRLEnvironmentMetricDefinitions

Section titled “BrowseRLEnvironmentMetricDefinitions”

Browses metric definitions scoped to RL environments within a run. Works like BrowseMetricDefinitions but filters to only RL-tagged series. Since metric definitions folders are sorted by each environment, at least one environment is required; multiple environments browse their union.

BrowseRLEnvironmentMetricDefinitionsRequest

Section titled “BrowseRLEnvironmentMetricDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run string
environment environment string Deprecated. DEPRECATED: Use environments instead. Treated as a single-element environments if environments is empty, ignored otherwise.
environments environments repeated string If not empty, browses the union of these environments — returns directories and metric definitions present in at least one of them, deduplicated. At most 1000 environments may be requested. At least one environment (in either field) is required.
directory directory string Directory to browse within. Empty string and “/” are treated as root.
regex regex optional string Optional regex to apply on all metric and directory names. This regex filter is applied to part of metric name AFTER directory stripped.
limit limit optional int64
resume_token resumeToken optional string

BrowseRLEnvironmentMetricDefinitionsAcrossRuns

Section titled “BrowseRLEnvironmentMetricDefinitionsAcrossRuns”

Browses RL environment metric definitions across multiple runs, scoped to a single directory level: the deduplicated union of directories and metric definitions over all environments of every requested run. Unlike BrowseRLEnvironmentMetricDefinitions no environment is given (nor required), by design — environment ids are not comparable across runs.

BrowseRLEnvironmentMetricDefinitionsAcrossRunsRequest

Section titled “BrowseRLEnvironmentMetricDefinitionsAcrossRunsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
runs runs repeated string Runs to browse in — returns directories and metric definitions present in at least one environment of at least one of these runs, deduplicated. At least 1 and at most 100 runs; duplicate names are deduplicated.
directory directory string Directory to browse within. Empty string and “/” are treated as root.
regex regex optional string Optional regex to apply on all metric and directory names. This regex filter is applied to part of metric name AFTER directory stripped.
limit limit optional int64
resume_token resumeToken optional string

ListSeriesDefinitions

Section titled “ListSeriesDefinitions”

Discovers full series definitions inside a project, experiment or run. Includes metric names, scale names, label keys and values. It does not contain RL specific series definitions.

ListSeriesDefinitionsRequest

Section titled “ListSeriesDefinitionsRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
experiment experiment optional string If specified, series definitions are scoped to this single experiment
run run optional string If specified, series definitions are scoped to this single run. Field experiment is ignored.
series_filters seriesFilters repeated string Optional. See series filter format. If omitted, returns all series types: regular series, aggregated series.
value_kinds valueKinds repeated SeriesValueKind Optional list. If not empty, only series definitions of these value kinds are returned. If empty, all value kinds are included.
limit limit optional int64 How many definitions to retrieve in this request. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If specified, resumes from last request. Other params like series filters (if given originally) must be still included in the request.

ListSeriesDefinitionsResponse

Section titled “ListSeriesDefinitionsResponse”
Field JSON Type Description
series_definitions seriesDefinitions repeated SeriesDefinition
resume_token resumeToken optional string Resume token to continue from (if any).

ListSeriesLabelValues

Section titled “ListSeriesLabelValues”

Returns distinct label values for specified label keys within specific runs across all metric/scale names. It works for RL and regular series.

ListSeriesLabelValuesRequest

Section titled “ListSeriesLabelValuesRequest”
Field JSON Type Description
workspace workspace string Name of the workspace.
organization organization optional string Slug of the organization owning the workspace. Workspace names are unique per organization, so this is required once another organization has a workspace of the same name; until then it may be omitted.
project project string Name of the project.
run run string Run to get label values from. Required.
label_key_filters labelKeyFilters repeated ListSeriesLabelValuesRequest.LabelKeyFilter Label key filters. Must contain at most 10 elements. If empty, server returns an empty response.
limit limit optional int64 How many values to retrieve per each requested label key. Omit or set to 0 to use the server default. Must be between 1 and 10000 if specified.
resume_token resumeToken optional string If provided, it will continue fetching more label values.

ListSeriesLabelValuesRequest.LabelKeyFilter

Section titled “ListSeriesLabelValuesRequest.LabelKeyFilter”
Field JSON Type Description
key key string Label key to return distinct values for, required.
value_prefix valuePrefix string
oneof value
value_regex valueRegex string
oneof value

ListSeriesLabelValuesResponse

Section titled “ListSeriesLabelValuesResponse”
Field JSON Type Description
label_key_values labelKeyValues repeated ListSeriesLabelValuesResponse.LabelKeyValues
resume_token resumeToken optional string Provided if there are more results awaiting.

ListSeriesLabelValuesResponse.LabelKeyValues

Section titled “ListSeriesLabelValuesResponse.LabelKeyValues”
Field JSON Type Description
key key string
values values repeated string