Skip to content
Metrana Docs

Series points

Paginated by total point count, depth-first (all series for run 1, then run 2, etc.). If the page limit is reached, a resume_token is returned; pass it in the next request to continue.

ListFloatSeries

Section titled “ListFloatSeries”

Returns float series points for specific runs. See series query format.

ListFloatSeriesRequest

Section titled “ListFloatSeriesRequest”
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_names runNames repeated string Required list of runs to fetch points from. Service will give empty results if this array is empty.
series_queries seriesQueries repeated string See series query format. If not populated, server responds with empty response
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
include_timestamps includeTimestamps bool If true, timestamp values will be returned along with points.
max_points_per_page maxPointsPerPage optional int64 How many at most points to retrieve in this request. If specified, must be between 1 and 10_000_000; value 0 is treated as the server default (1_000_000), same as omitting. This limit is for all series combined. It is meant as a protection against too big responses, but it is not necessarily 100% accurate. Server may return a bit less points than maximum per page if point counters are yet to be updated.
resume_token resumeToken optional string If specified, server responds with next point values. This value must be retrieved from previous ListFloatSeriesResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to retrieve from each of series. See StepSelection message for details.

ListFloatSeriesResponse

Section titled “ListFloatSeriesResponse”
Field JSON Type Description
run_points runPoints repeated ListFloatSeriesResponse.RunPoints
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.

ListFloatSeriesResponse.RunPoints

Section titled “ListFloatSeriesResponse.RunPoints”
Field JSON Type Description
run run string
series series repeated SeriesPoints

ListFloatSeriesBuckets

Section titled “ListFloatSeriesBuckets”

Returns float series point buckets for specific runs. See series query format.

ListFloatSeriesBucketsRequest

Section titled “ListFloatSeriesBucketsRequest”
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_names runNames repeated string Required list of runs to fetch points from. Service will give empty results if this array is empty.
series_queries seriesQueries repeated string See series query format. If not populated, server responds with empty response.
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
include_timestamps includeTimestamps bool If true, series in response will contain timestamps.
max_buckets_per_page maxBucketsPerPage optional int64 How many at most points to retrieve in this request. If specified, must be between 1 and 1_000_000 (default). Value 0 is treated as default. This limit is for all series combined.
max_buckets_across_series maxBucketsAcrossSeries optional int64 Caps the total number of buckets across all series (all pages combined). Must not be negative. Value 0 is treated as unset. If set, the per-series buckets count becomes: min(buckets_count, max_buckets_across_series / series_count) where series_count is the number of series matched by the request. At least 1 bucket per series is always produced, even if the division gives 0. The count actually used is reported in the response as effective_buckets_count. Note: if this is equal to max_buckets_per_page, all buckets fit in the first page and pagination never continues.
buckets_count bucketsCount optional int64 How many per-series buckets response must contain. If specified, must be between 1 and 5000. Value 0 is treated as default. Default value is 1000. But there is important caveat: If all series are too short to produce at requested buckets count (for example, buckets count is 1000, but the longest series gives 900 steps), then this value is automatically lowered to 900.
resume_token resumeToken optional string If specified, server responds with next point values. This value must be retrieved from previous ListFloatSeriesBucketsResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to retrieve from each of series. See StepSelection message for details.
use_columnar_output useColumnarOutput bool

ListFloatSeriesBucketsResponse

Section titled “ListFloatSeriesBucketsResponse”
Field JSON Type Description
run_series runSeries RunSeriesBuckets Series buckets for all runs.
run_points runPoints repeated ListFloatSeriesBucketsResponse.RunPoints
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.
first_step firstStep uint64 Global first step across all series in this response. All series buckets are aligned to the same [first_step, last_step] range.
last_step lastStep uint64 Global last step across all series in this response.
bucket_step_width bucketStepWidth double Number of steps each bucket covers. Computed as: (last_step - first_step + 1) / buckets_count where buckets_count is the number of buckets per series. Client can compute start of bucket i as: first_step + floor(i * bucket_step_width)

ListFloatSeriesBucketsResponse.RunPoints

Section titled “ListFloatSeriesBucketsResponse.RunPoints”
Field JSON Type Description
run run string
series series repeated SeriesBuckets

ListHistogramSeries

Section titled “ListHistogramSeries”

Returns histogram series points (both counting and density kinds) for specific runs. See series query format — transformations are not supported here; queries matching non-histogram series yield no rows. Histogram points are heavy (KBs per point), so page limits are much lower than for float series.

ListHistogramSeriesRequest

Section titled “ListHistogramSeriesRequest”
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_names runNames repeated string Required list of runs to fetch points from. Service will give empty results if this array is empty.
series_queries seriesQueries repeated string See series query format. Transformations are rejected — histogram series have no scalar transform semantics (reductions to float series are served by the float endpoints instead). Queries matching non-histogram series yield no rows. If not populated, server responds with empty response.
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
include_timestamps includeTimestamps bool If true, timestamp values will be returned along with points.
max_points_per_page maxPointsPerPage optional int64 How many at most points to retrieve in this request. If specified, must be between 1 and 10_000; value 0 is treated as the server default (1_000), same as omitting. This limit is for all series combined. Histogram points weigh up to ~8KiB each (512 bins, ~0.5-1KiB typical), so the worst-case page is ~80MiB — well above default gRPC message limits; raise them or page smaller.
resume_token resumeToken optional string If specified, server responds with next point values. This value must be retrieved from previous ListHistogramSeriesResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to retrieve from each of series. See StepSelection message for details.
include_series_extent includeSeriesExtent bool If true, each returned series carries its step extent and approximate point count (HistogramSeriesData.extent), computed from a cheap primary-key scan. Lets a client render e.g. a step slider from a single last-point request and then fetch ranges with full knowledge of what exists. Extents are only reported for series with points in the current page; a series whose step selection matches nothing is absent from the response entirely.

ListHistogramSeriesResponse

Section titled “ListHistogramSeriesResponse”
Field JSON Type Description
run_points runPoints repeated ListHistogramSeriesResponse.RunPoints
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.

ListHistogramSeriesResponse.RunPoints

Section titled “ListHistogramSeriesResponse.RunPoints”
Field JSON Type Description
run run string
series series repeated HistogramSeriesData

ListScatterSeries

Section titled “ListScatterSeries”

Returns scatter series points (2D and 3D kinds) for specific runs. See series query format — transformations and functions are not supported; queries matching non-scatter series yield no rows. This is the ONLY endpoint serving scatter points: no scatter→float reduction exists. Paging counts individual data points, and a step’s point set is never split (see max_data_points_per_page).

ListScatterSeriesRequest

Section titled “ListScatterSeriesRequest”
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_names runNames repeated string Required list of runs to fetch points from. Service will give empty results if this array is empty.
series_queries seriesQueries repeated string See series query format. Transformations and functions are rejected — scatter series define no reductions (there is no scatter counterpart of value_reducer). value_kind=scatter / value_kind=scatter_3d may narrow the served kind; queries matching non-scatter series yield no rows. If not populated, server responds with empty response.
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
include_timestamps includeTimestamps bool If true, timestamp values will be returned along with points.
max_data_points_per_page maxDataPointsPerPage optional int64 Page budget in individual DATA POINTS — 2D or 3D coordinates — summed across all series. If specified, must be between 1 and 1_000_000; value 0 is treated as the server default (100_000), same as omitting. A step’s point set is atomic: it is never split across pages, and a page always advances by at least one whole set, even when that single set alone exceeds the budget. Page cuts inside a series are planned from per-series average set sizes, so the budget is approximate: a page may overshoot it in proportion to how strongly set sizes vary within one series.
resume_token resumeToken optional string If specified, server responds with next point values. This value must be retrieved from previous ListScatterSeriesResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to retrieve from each of series. See StepSelection message for details.
include_series_extent includeSeriesExtent bool If true, each returned series carries its step extent, approximate step count and approximate total data point count (ScatterSeriesData.extent). Lets a client render e.g. a step slider from a single last-point request and then fetch ranges with full knowledge of what exists. Extents are only reported for series with points in the current page; a series whose step selection matches nothing is absent from the response entirely.

ListScatterSeriesResponse

Section titled “ListScatterSeriesResponse”
Field JSON Type Description
run_points runPoints repeated ListScatterSeriesResponse.RunPoints
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.

ListScatterSeriesResponse.RunPoints

Section titled “ListScatterSeriesResponse.RunPoints”
Field JSON Type Description
run run string
series series repeated ScatterSeriesData

ListFloatSeriesTimestampBuckets

Section titled “ListFloatSeriesTimestampBuckets”

Returns float series point buckets bucketed by TIMESTAMP (not step) for specific runs. See series query format. Unlike ListFloatSeriesBuckets, the bucketing axis is wall-clock time: each bucket covers a fixed span of milliseconds, and the selection range is a timestamp range rather than a step range. Output is always columnar. Timestamps may be absolute (millis since epoch) or relative to run start (see use_relative_timestamp).

ListFloatSeriesTimestampBucketsRequest

Section titled “ListFloatSeriesTimestampBucketsRequest”
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_names runNames repeated string Required list of runs to fetch points from. Service will give empty results if this array is empty.
series_queries seriesQueries repeated string See series query format. If not populated, server responds with empty response.
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
max_buckets_per_page maxBucketsPerPage optional int64 How many at most buckets to retrieve in this request. If specified, must be between 1 and 1_000_000 (default). Value 0 is treated as default. This limit is for all series combined.
max_buckets_across_series maxBucketsAcrossSeries optional int64 Caps the total number of buckets across all series (all pages combined). Must not be negative. Value 0 is treated as unset. See ListFloatSeriesBucketsRequest.max_buckets_across_series for exact semantics.
buckets_count bucketsCount optional int64 How many per-series buckets response must contain. If specified, must be between 1 and 5000. Value 0 is treated as default. Default value is 1000. But there is important caveat: If all series span too short a time range to produce the requested buckets count at >= 1 millisecond per bucket, then this value is automatically lowered.
resume_token resumeToken optional string If specified, server responds with next bucket values. This value must be retrieved from previous ListFloatSeriesTimestampBucketsResponse. Provision of this token does not remove a need to repeat other request fields.
timestamp_range timestampRange optional TimestampRange Selects the wall-clock timestamp range of data points to retrieve from each series. See TimestampRange message for details.
use_relative_timestamp useRelativeTimestamp bool If true, all timestamps — both the request range and the response values — are expressed as milliseconds since the run started, rather than milliseconds since epoch. This lets the client align multiple runs to a common t=0 (each run relative to its own start).

ListFloatSeriesTimestampBucketsResponse

Section titled “ListFloatSeriesTimestampBucketsResponse”
Field JSON Type Description
run_series runSeries RunSeriesTimestampBuckets Timestamp-bucketed series for all runs.
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.

AggregateRunSeries

Section titled “AggregateRunSeries”

Aggregates float series across runs into bucketed chart lines. See series query format. Runs are given as groups; every matched series identity is aggregated separately within each group: at each step the values of the group’s runs are reduced by every requested aggregation, then the per-step results are bucketed exactly like ListFloatSeriesBuckets buckets raw points (average, min, max and count per bucket). A run may appear in several groups. Output is one series per (group, series identity), paginated by total bucket count like ListFloatSeriesBuckets.

AggregateRunSeriesRequest

Section titled “AggregateRunSeriesRequest”
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.
groups groups repeated AggregateRunSeriesRequest.RunsList Run groups to aggregate within. Every group is aggregated on its own; a run may be listed in several groups. Empty groups are skipped. Service responds with an empty response if no group holds a run.
series_queries seriesQueries repeated string See series query format. Float series only: value_kind declarations (histograms, scatter) are rejected, and like ListFloatSeriesBuckets no transformations after | are allowed. If not populated, server responds with empty response.
aggregations aggregations repeated RunSeriesAggregation Reductions to compute at each step, in response order. At least one is required; duplicates are rejected.
include_inherited includeInherited bool If true, points inherited as a result of forking contribute too.
max_buckets_per_page maxBucketsPerPage optional int64 How many at most buckets to retrieve in this request, across all aggregated series. If specified, must be between 1 and 1_000_000 (default). Value 0 is treated as default.
max_buckets_across_series maxBucketsAcrossSeries optional int64 Caps the total number of buckets across all aggregated series (all pages combined). See ListFloatSeriesBucketsRequest.max_buckets_across_series for exact semantics; series_count is the number of aggregated series (group x series identity pairs) matched by the request.
buckets_count bucketsCount optional int64 How many buckets each aggregated series must contain. If specified, must be between 1 and 5000. Value 0 is treated as default (1000). Lowered automatically when the step range is shorter, exactly like ListFloatSeriesBucketsRequest.buckets_count.
resume_token resumeToken optional string If specified, server responds with the next aggregated series. This value must be retrieved from previous AggregateRunSeriesResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to aggregate from each of series. See StepSelection message for details. The step range is global across all runs of all groups, like in ListFloatSeriesBuckets.

AggregateRunSeriesRequest.RunsList

Section titled “AggregateRunSeriesRequest.RunsList”
Field JSON Type Description
runs runs repeated string

AggregateRunSeriesResponse

Section titled “AggregateRunSeriesResponse”
Field JSON Type Description
series series repeated AggregateRunSeriesResponse.AggregatedSeries All aggregated series within a response, ordered by group index, then series identity.
first_step firstStep uint64 First step in the first bucket across all series.
last_step lastStep uint64 Last step in the last bucket across all series.
steps_per_bucket stepsPerBucket double Number of steps in each bucket; see RunSeriesBuckets.steps_per_bucket.
buckets_count bucketsCount int64 Final number of buckets. It will be same as requested, unless all series were shorter.
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.

AggregateRunSeriesResponse.BucketedAggregatedPoints

Section titled “AggregateRunSeriesResponse.BucketedAggregatedPoints”
Field JSON Type Description
aggregation aggregation RunSeriesAggregation Which requested aggregation these values belong to.
y_values yValues repeated double Average of the per-step aggregated values in each bucket. Index-aligned with AggregatedSeries.bucket_indexes.
min_values minValues repeated double Minimum of the per-step aggregated values in each bucket. Array is empty if number of steps per bucket is exactly 1, as min values would be exactly same as y_values.
max_values maxValues repeated double Maximum of the per-step aggregated values in each bucket. Array is empty if number of steps per bucket is exactly 1, as max values would be exactly same as y_values.

AggregateRunSeriesResponse.AggregatedSeries

Section titled “AggregateRunSeriesResponse.AggregatedSeries”

One aggregated line: one series identity over the runs of one group. Same empty-bucket semantics as RunSeriesBuckets.SingleSeries: only buckets holding at least one finite step are listed in bucket_indexes.

Field JSON Type Description
group_index groupIndex uint32 Index into the request’s groups. Runs of the group without the series simply do not contribute.
series_definition seriesDefinition SeriesDefinition Full series definition.
bucket_indexes bucketIndexes repeated uint64 Bucket indexes holding data, ascending. Every array below (and in aggregated_buckets) that is set has the same length.
aggregated_buckets aggregatedBuckets repeated AggregateRunSeriesResponse.BucketedAggregatedPoints One entry per requested aggregation, in request order.
counts counts repeated uint64 Number of merged steps in each bucket: steps where at least one run of the group had a finite value, not raw points across runs. Array is empty if number of steps per bucket is exactly 1, as counts would be always 1 anyway.
buckets_with_nans bucketsWithNans repeated uint64 Ascending indexes of buckets where at least one run had a NaN point. NaN/Inf points never contribute to the aggregations — a bucket whose points are ALL non-finite is therefore absent from bucket_indexes and only listed here.
buckets_with_infs bucketsWithInfs repeated uint64 Same as buckets_with_nans, for +Inf points.
buckets_with_neg_infs bucketsWithNegInfs repeated uint64 Same as buckets_with_nans, for -Inf points.

ListRLEnvironmentFloatSeriesBuckets

Section titled “ListRLEnvironmentFloatSeriesBuckets”

Returns float RL specific series point buckets for specific runs. See series query format.

ListRLEnvironmentFloatSeriesBucketsRequest

Section titled “ListRLEnvironmentFloatSeriesBucketsRequest”
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, fetches series from the union of these environments (compare / side-by-side view). At most 1000 environments may be requested. If any environment is given, environment field is ignored. More than one environment requires use_specialized_rl_series_buckets — only the specialized response layouts carry a per-series environment.
scale_selector scaleSelector RLScaleSelector
series_queries seriesQueries repeated string See series query format. If not populated, server responds with empty response.
include_inherited includeInherited bool If true, returned points will include inherited as a result of forking.
include_timestamps includeTimestamps bool If true, series in response will contain timestamps.
max_buckets_per_page maxBucketsPerPage optional int64 How many at most points to retrieve in this request. If specified, must be between 1 and 1_000_000 (default). Value 0 is treated as default. This limit is for all series combined.
max_buckets_across_series maxBucketsAcrossSeries optional int64 Caps the total number of buckets across all series (all pages combined). Must not be negative. Value 0 is treated as unset. See ListFloatSeriesBucketsRequest.max_buckets_across_series for exact semantics.
buckets_count bucketsCount optional int64 How many per-series buckets response must contain. If specified, must be between 1 and 5000. Value 0 is treated as default. Default value is 1000. But there is important caveat: If all series are too short to produce at requested buckets count (for example, buckets count is 1000, but the longest series gives 900 steps), then this value is automatically lowered to 900.
resume_token resumeToken optional string If specified, server responds with next point values. This value must be retrieved from previous ListRLEnvironmentFloatSeriesBucketsResponse. Provision of this token does not remove a need to repeat other request fields.
step_selection stepSelection optional StepSelection Selects range of data points to retrieve from each of series. See StepSelection message for details.
use_specialized_rl_series_buckets useSpecializedRlSeriesBuckets bool

ListRLEnvironmentFloatSeriesBucketsResponse

Section titled “ListRLEnvironmentFloatSeriesBucketsResponse”
Field JSON Type Description
series series repeated SeriesBuckets
rl_series_on_episode_selector rlSeriesOnEpisodeSelector RlSeriesBucketsOnEpisodeSelector
oneof rl_specialized_series
rl_series_on_rl_step_selector rlSeriesOnRlStepSelector RlSeriesBucketsOnRlStepSelector
oneof rl_specialized_series
resume_token resumeToken optional string Present if more pages remain. Pass as resume_token in the next request. It is required that other request fields are still repeated.
first_step firstStep uint64 Global first step across all series in this response. All series buckets are aligned to the same [first_step, last_step] range.
last_step lastStep uint64 Global last step across all series in this response.
bucket_step_width bucketStepWidth double Number of steps each bucket covers. Computed as: (last_step - first_step + 1) / buckets_count where buckets_count is the number of buckets per series. Client can compute start of bucket i as: first_step + floor(i * bucket_step_width)

AggregateRLEnvironmentSeries

Section titled “AggregateRLEnvironmentSeries”

Aggregates one RL series across environments into chart lines. At each x (rl_step or episode of range_selector) the series is reduced per environment by the series_expression function, then across environments by aggregation. Environment filters are re-evaluated at every x; groupings split the output into multiple lines.

AggregateRLEnvironmentSeriesRequest

Section titled “AggregateRLEnvironmentSeriesRequest”
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
range_selector rangeSelector RLScaleRangeSelector X axis of the chart: inclusive rl_step or episode range. Required. The x unit of the response follows the picked scale. The server rejects requests producing more OUTPUT points than its configured limit — the resolved range’s x count when unbucketed, buckets_count under bucketing — and bucketed requests whose single bucket would exceed one query’s scan budget (narrow the range or request more buckets).
series_expression seriesExpression string The charted series: $METRIC_NAME([scale=$SCALE,] [filter=($LABEL_CONDITIONS)]):$FUNC (see series summary formats), with these restrictions:
• function is required and single-valued: first, last, min, max, sum, avg, count, std
• label conditions may use any operator and need not be fully specified. Where they resolve to several of an environment’s series, the function is computed across them at each (x, environment) — see label resolution and across-series aggregation — which rules out first/last there (pin every label key to use those).
Note: $SCALE here is part of the series identity (as everywhere in series summary formats) and is unrelated to the x axis; the x axis (rl_step or episode) comes from range_selector. The function reduces the series within each (x, environment) cell; aggregation then reduces those values across environments at each x. On episode scale the series must be episodic; an in-progress episode contributes with its data logged so far.
aggregations aggregations repeated RLEnvironmentsAggregation Cross-environment reductions applied at each x — one values array is returned per entry, in this order (see AggregatedRlSeries). Must be non-empty and duplicate-free; only what is requested is computed. Contributing environment counts are always returned alongside, so e.g. a mean line with a 95% confidence band is [AVG, STD] plus the client-side mean ± 1.96 * std / sqrt(count).
filter filter optional string Optional environment filter — a single condition or an AND/OR chain with parentheses (see resource filter format). Supported conditions:
• series summary conditions, with the same rules as series_expression (required function; labels resolved the same way). Re-evaluated at EVERY x of the range, so the contributing environment set may differ between points on the x axis; an environment with no data for the condition’s series at a given x does not match at that x.
• attr($PATH) conditions on user attributes, with carry-forward semantics: at each x the value in effect is the latest revision logged at-or-before x, so a re-logged attribute moves environments between matching and not along the x axis.
• attr(environment_id) conditions — a constant environment subset (e.g. environment_id IN […]). The other reserved fields (latest_episode, latest_rl_step) are REJECTED here: they are run-global latest values with no per-x meaning.
groupings groupings repeated string Optional chart groupings. Each entry is one of:
• attr($ATTR_PATH) — a string environment attribute. The group key at each x is the value in effect there (the latest revision logged at-or-before x, same carry-forward semantics as attr conditions in filter), so a re-logged attribute moves an environment between groups along x. Environments with no value in effect at x form a dedicated group (see GroupKeyPart.unset).
• a boolean attribute condition (attr($PATH) CONTAINS “x”, attr($PATH) >= 3, attr($PATH) EXISTS, …) — any attribute type, operators as in filter, evaluated over the value in effect at each x (carry-forward). For comparisons, environments with no value in effect at x form the unset group — the condition is neither true nor false there; EXISTS instead maps them to false (no value IS the definitive answer).
• a boolean series summary condition, same format and restrictions as in filter — re-evaluated at every x, so one environment may contribute to different groups at different x. For a comparison condition, an environment with no data for the condition’s series at x belongs to neither group and is dropped at that x; a bare EXISTS condition instead maps missing data to the false group.
• attr(environment_id) — one group (series) per environment: the compare-a-few-environments case. Combine with a filter selecting the environments of interest; an unfiltered request is rejected upfront when the run’s environment count exceeds the output-series limit. Condition forms on environment_id are rejected — selecting environments is filter’s job.
One aggregated series is produced per observed combination of grouping values, keyed by series_key_parts in this list’s order. Every boolean grouping multiplies the potential series count (by 2, or by 3 for attribute comparisons, which may also be unset); the server rejects requests whose potential boolean combination count exceeds its configured output-series limit and aborts requests whose observed combination count exceeds it.
buckets_count bucketsCount optional int64 Optional x-axis compression: at most this many output points (buckets) over the resolved range. Unset/0, or a value at least the range’s x count, means one point per x; negative values are rejected. Bucket widths are distributed exactly (floor/ceil of range/buckets interleaved). Mutually exclusive with bucket_width — setting both to a non-zero value is rejected.

Semantics under bucketing: filters, groupings and the per-environment series function keep their per-x meaning — each environment’s bucket value is the series_expression function applied over ALL its data at the bucket’s x positions where it matched the filter (exact, not an approximation: pooled from the underlying stats). The cross-environment aggregation then reduces those per-environment values, so e.g. MEDIAN is the median of per-environment pooled values. An environment whose group key changes mid-bucket contributes one pooled value per group it visited, so per-group counts within a bucket may sum above the environment total.
bucket_width bucketWidth optional double Optional x-axis compression by a fixed bucket width in x units: the range is cut into ceil(range / bucket_width) buckets, so runs of different lengths line up bucket for bucket. Buckets fall on the same x positions for every run asked for the same width, provided the requests also share a range start — the grid is anchored at the resolved range’s first x. Bucketing semantics are otherwise as for buckets_count.

Mutually exclusive with buckets_count; setting both non-zero is rejected, as are negative, NaN and infinite values. Unset/0 means no width compression, and a width of 1 or below gives one point per x.

AggregateRLEnvironmentSeriesResponse

Section titled “AggregateRLEnvironmentSeriesResponse”
Field JSON Type Description
series series repeated AggregateRLEnvironmentSeriesResponse.AggregatedRlSeries

AggregateRLEnvironmentSeriesResponse.GroupKeyPart

Section titled “AggregateRLEnvironmentSeriesResponse.GroupKeyPart”
Field JSON Type Description
bool_value boolValue bool
oneof value		 Outcome of a boolean series-condition grouping.
string_value stringValue string
oneof value		 Value of a string attribute grouping.
unset unset bool
oneof value		 Always true when set: environments in this group had no value in effect for the grouping attribute. Distinct from string_value = “”.

AggregateRLEnvironmentSeriesResponse.AggregationValues

Section titled “AggregateRLEnvironmentSeriesResponse.AggregationValues”
Field JSON Type Description
aggregation aggregation RLEnvironmentsAggregation Which requested aggregation these values belong to.
values values repeated double The reduction at each x; index-aligned with first_steps.

AggregateRLEnvironmentSeriesResponse.AggregatedRlSeries

Section titled “AggregateRLEnvironmentSeriesResponse.AggregatedRlSeries”
Field JSON Type Description
series_key_parts seriesKeyParts repeated AggregateRLEnvironmentSeriesResponse.GroupKeyPart One entry per request grouping, in the same order. Empty when the request had no groupings.
first_steps firstSteps repeated uint64 x position (rl_step or episode, per range_selector), ascending. Under bucketing (buckets_count) this is the first x position with contributing data in the bucket for this series.
counts counts repeated uint64 Number of environments contributing at each x (after filters). Varies along x: environments may not have reached x, may have no data at x, or may fail per-x series conditions only at some x. Always returned.
aggregations aggregations repeated AggregateRLEnvironmentSeriesResponse.AggregationValues One entry per requested aggregation, in request order.