Message types

Messages and enums reachable from the RPC request and response messages. Request and response messages themselves are documented next to their RPC. Field names are shown as declared in the .proto files and in the camelCase form the REST API uses in JSON.

metrana_protobuf.query.v1.svc

AttrDefDirectorySource

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`directory_path`	`directoryPath`	optional `string`	If set, discover attributes of this directory only. If unset, discover across all directories in the project.

AttrDefExperimentSource

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`experiment`	`experiment`	optional `string`	If set, discover attributes of this experiment only. If unset, discover across all experiments in the project.

AttrDefProjectSource

Selects which resource type to discover attributes for. Exactly one must be set. Within each source, optional fields narrow discovery to a specific resource instance; if omitted, discovery spans all resources of that type.

Field	JSON	Type	Description
`project`	`project`	optional `string`	If set, discover attributes of this project only. If unset, discover across all projects in the workspace.

AttrDefRunSource

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`experiment`	`experiment`	optional `string`	If set (without run=), scopes to runs belonging to this experiment.
`run`	`run`	optional `string`	If set, discover attributes of this run only. If unset, discover across all runs in the project (or experiment).

AttrDirectorySource

Selects directory to fetch attributes from

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`directory_path`	`directoryPath`	`string`

AttrExperimentSource

Selects experiment to fetch attributes from

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`experiment`	`experiment`	`string`

AttributeDef

Field	JSON	Type	Description
`path`	`path`	`string`
`kind`	`kind`	AttributeKind

AttrProjectSource

Selects project to fetch attributes from

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.

AttrRunSource

Selects run to fetch attributes from

Field	JSON	Type	Description
`project`	`project`	`string`	Name of the project.
`run`	`run`	`string`

BrowseAttrFilter

BrowseAttrFilter is used for browsing attribute definitions and values in directory context.

Field	JSON	Type	Description
`kinds`	`kinds`	repeated AttributeKind	If set, only return attributes of the specified kinds.

HistogramSeriesData

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition for given points. The definition kind distinguishes counting histograms from density ones.
`points`	`points`	HistogramSeriesPoints	Compact columnar list of histogram points.
`extent`	`extent`	optional HistogramSeriesData.SeriesExtent	Present when the request set include_series_extent.

HistogramSeriesData.SeriesExtent

Step extent of the whole series, independent of the request’s step selection.

Field	JSON	Type	Description
`first_step`	`firstStep`	`uint64`	First and last steps that exist for this series (exact).
`last_step`	`lastStep`	`uint64`
`points_count`	`pointsCount`	`uint64`	Approximate total point count: pre-deduplication row count, an upper bound of the number of distinct steps.

KeyedSeriesSummary

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition
`summary_values`	`summaryValues`	SeriesSummary

ListAttrFilter

ListAttrFilter is used for listing attribute definitions and values

Field	JSON	Type	Description
`kinds`	`kinds`	repeated AttributeKind	If set, only return attributes of the specified kinds.
`all`	`all`	ListAttrFilter.AllAttributes oneof `name_filter`	Return all attributes with no path filtering.
`regex`	`regex`	`string` oneof `name_filter`	Return only attributes whose full path matches this regex. Note: This is not implemented for attributes browsing, will result in InvalidArgument error.
`prefix_path`	`prefixPath`	`string` oneof `name_filter`	List immediate children at this path prefix.

ListAttrFilter.AllAttributes

This message has no fields.

MetricDefinition

A single metric definition — shared by List and Browse responses.

Field	JSON	Type	Description
`metric_name`	`metricName`	`string`
`scale`	`scale`	`string`
`label_keys`	`labelKeys`	repeated `string`
`is_aggregated`	`isAggregated`	`bool`
`value_kind`	`valueKind`	SeriesValueKind	Value type of this metric’s series points. The same metric name may appear once per value kind if runs logged it with different kinds.

RLEnvironmentsAggregation

Cross-environment reduction applied at each x over per-environment values. The contributing environment count is not an aggregation — it is always returned (see AggregatedRlSeries.counts).

Value	Number	Description
`RL_ENVIRONMENTS_AGGREGATION_UNSPECIFIED`	0
`RL_ENVIRONMENTS_AGGREGATION_AVG`	1
`RL_ENVIRONMENTS_AGGREGATION_MIN`	2
`RL_ENVIRONMENTS_AGGREGATION_MAX`	3
`RL_ENVIRONMENTS_AGGREGATION_SUM`	4
`RL_ENVIRONMENTS_AGGREGATION_STD`	5	Sample standard deviation (n-1) of per-environment values; 0 when a single environment contributes.
`RL_ENVIRONMENTS_AGGREGATION_MEDIAN`	6	Exact interpolated median of per-environment values.

RLScaleRangeSelector

X-axis range for cross-environment aggregations. Mirrors RLScaleSelector but selects an inclusive range instead of a single point. Open StepRange ends are resolved by the server: unset from_step means 0, unset to_step means the largest rl_step/episode recorded by any environment of the run.

Field	JSON	Type	Description
`rl_step_range`	`rlStepRange`	StepRange oneof `scale`
`episode_range`	`episodeRange`	StepRange oneof `scale`

RLScaleSelector

Field	JSON	Type	Description
`rl_step`	`rlStep`	`uint64` oneof `scale`
`episode`	`episode`	`uint64` oneof `scale`

RlSeriesBucketsOnEpisodeSelector

Field	JSON	Type	Description
`series`	`series`	repeated RlSeriesBucketsOnEpisodeSelector.SingleSeries	All series within a response. Each has exactly as many buckets as number of requested buckets in the request (default is 1000).
`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. Minimum value here will be 1.0, in which case one step was put inside each bucket. If series were long enough, one bucket will hold more steps, on average indicated in this value.
`buckets_count`	`bucketsCount`	`int64`	Final number of buckets. It will be same as requested, unless all series were shorter.

RlSeriesBucketsOnEpisodeSelector.SingleSeries

SingleSeries is a columnar oriented series storage. It is important to note that, despite all series sharing common first/last step, steps per bucket, and buckets count, number of values may actually differ, if some buckets for specific series are empty. Client needs to check bucket_indexes array. If first value is larger than 0, it means that up to N first buckets are empty. If there is a jump in values (from 0 to 2 for example), then bucket 1 was empty. If last value is lower than number of buckets minus 1, then last buckets were empty.

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition
`environment`	`environment`	`string`	Environment holding this series. Always set — disambiguates series sharing the same definition across environments in multi-environment requests.
`bucket_indexes`	`bucketIndexes`	repeated `uint64`	Bucket index. Length of this array is same as for all the other arrays, if they are set. Bucket indexes show which buckets are filled, and should be used to detect empty ones.
`y_values`	`yValues`	repeated `double`	Average of values in each bucket
`counts`	`counts`	repeated `uint64`	Number of values in each bucket. Array is empty if number of steps per bucket is exactly 1, as counts would be always 1 anyway.
`min_values`	`minValues`	repeated `double`	Minimum value 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 value 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.
`last_timestamp_millis`	`lastTimestampMillis`	repeated `int64`	Timestamp of the last point in each bucket (youngest) If include timestamp was false in the request, it is empty array.
`last_rl_steps`	`lastRlSteps`	repeated `uint64`	Last rl step in each bucket.
`buckets_with_nans`	`bucketsWithNans`	repeated `uint64`	Ascending indexes of buckets holding at least one NaN point. NaN/Inf points never contribute to y_values/counts/min/max — 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.

RlSeriesBucketsOnRlStepSelector

Field	JSON	Type	Description
`series`	`series`	repeated RlSeriesBucketsOnRlStepSelector.SingleSeries	All series within a response. Each has exactly as many buckets as number of requested buckets in the request (default is 1000).
`first_rollout_idx`	`firstRolloutIdx`	`uint64`	First rollout index in the first bucket across all series.
`last_rollout_idx`	`lastRolloutIdx`	`uint64`	Last rollout index in the last bucket across all series.
`rollout_indexes_per_bucket`	`rolloutIndexesPerBucket`	`double`	Number of rollout indexes in each bucket. Minimum value here will be 1.0, in which case one index was put inside each bucket. If series were long enough, one bucket will hold more indexes, on average indicated in this value.
`buckets_count`	`bucketsCount`	`int64`	Final number of buckets. It will be same as requested, unless all series were shorter.

RlSeriesBucketsOnRlStepSelector.SingleSeries

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition
`environment`	`environment`	`string`	Environment holding this series. Always set — disambiguates series sharing the same definition across environments in multi-environment requests.
`bucket_indexes`	`bucketIndexes`	repeated `uint64`	Bucket index. Length of this array is same as for all the other arrays, if they are set. Bucket indexes show which buckets are filled, and should be used to detect empty ones.
`y_values`	`yValues`	repeated `double`	Average of values in each bucket
`counts`	`counts`	repeated `uint64`	Number of values in each bucket. Array is empty if number of steps per bucket is exactly 1, as counts would be always 1 anyway.
`min_values`	`minValues`	repeated `double`	Minimum value 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 value 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.
`last_timestamp_millis`	`lastTimestampMillis`	repeated `int64`	Timestamp of the last point in each bucket (youngest) If include timestamp was false in the request, it is empty array.
`episodes`	`episodes`	repeated `uint64`	Assigned episode to points in the bucket. Array is empty if series is not episodic.
`last_env_steps`	`lastEnvSteps`	repeated `uint64`	Last env step in each bucket Array is empty if series is not on environment step scale.
`buckets_with_nans`	`bucketsWithNans`	repeated `uint64`	Ascending indexes of buckets holding at least one NaN point. NaN/Inf points never contribute to y_values/counts/min/max — 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.

RunSeriesAggregation

Cross-run reduction applied at each step over the values of a group’s runs. The contributing step count is not an aggregation — it is always returned (see AggregatedSeries.counts).

Value	Number	Description
`RUN_SERIES_AGGREGATION_UNSPECIFIED`	0
`RUN_SERIES_AGGREGATION_AVG`	1
`RUN_SERIES_AGGREGATION_MIN`	2
`RUN_SERIES_AGGREGATION_MAX`	3
`RUN_SERIES_AGGREGATION_SUM`	4
`RUN_SERIES_AGGREGATION_STD`	5	Sample standard deviation (n-1) of per-run values; 0 when a single run contributes at a step.
`RUN_SERIES_AGGREGATION_MEDIAN`	6	Exact interpolated median of per-run values (the mean of the two middle values for an even count).

RunSeriesBuckets

Field	JSON	Type	Description
`series`	`series`	repeated RunSeriesBuckets.SingleSeries	All series within a response. Each has exactly as many buckets as number of requested buckets in the request (default is 1000).
`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. Minimum value here will be 1.0, in which case one step was put inside each bucket. If series were long enough, one bucket will hold more steps, on average indicated in this value.
`buckets_count`	`bucketsCount`	`int64`	Final number of buckets. It will be same as requested, unless all series were shorter.

RunSeriesBuckets.SingleSeries

Field	JSON	Type	Description
`run`	`run`	`string`	Run identifier holding this series.
`definition`	`definition`	SeriesDefinition	Full series definition
`bucket_indexes`	`bucketIndexes`	repeated `uint64`	Bucket index. Length of this array is same as for all the other arrays, if they are set. Bucket indexes show which buckets are filled, and should be used to detect empty ones.
`y_values`	`yValues`	repeated `double`	Average of values in each bucket
`counts`	`counts`	repeated `uint64`	Number of values in each bucket. Array is empty if number of steps per bucket is exactly 1, as counts would be always 1 anyway.
`min_values`	`minValues`	repeated `double`	Minimum value 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 value 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.
`last_timestamp_millis`	`lastTimestampMillis`	repeated `int64`	Timestamp of the last point in each bucket (youngest) If include timestamp was false in the request, it is empty array.
`buckets_with_nans`	`bucketsWithNans`	repeated `uint64`	Ascending indexes of buckets holding at least one NaN point. NaN/Inf points never contribute to y_values/counts/min/max — 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.

RunSeriesTimestampBuckets

Columnar series buckets where the bucketing axis is wall-clock TIMESTAMP rather than step. Mirrors RunSeriesBuckets, but every bucket spans a fixed number of milliseconds instead of a fixed number of steps.

Field	JSON	Type	Description
`series`	`series`	repeated RunSeriesTimestampBuckets.SingleSeries	All series within a response. Each has exactly as many buckets as number of requested buckets in the request (default is 1000).
`first_timestamp_millis`	`firstTimestampMillis`	`int64`	Lower edge of the first bucket — the ORIGIN of the bucketing axis, not the first non-empty bucket. Leading buckets may be empty when a run’s first point is logged after this origin; that is expected and unavoidable while honoring the contract below. Frame follows use_relative_timestamp: • relative (true): always 0 — each run’s t=0 is its own start. • absolute (false): the earliest run start among the returned runs (millis since epoch), so all runs share one timeline. If the request set timestamp_range.from_timestamp_millis, that bound is used instead, clamped up to the origin above.
`last_timestamp_millis`	`lastTimestampMillis`	`int64`	Upper edge of the last bucket, in the same frame as first_timestamp_millis. With an open-ended request end this is the youngest point across all returned series; otherwise it is the requested to_timestamp_millis.
`millis_per_bucket`	`millisPerBucket`	`double`	Number of milliseconds each bucket covers. Minimum value here will be 1.0, in which case one millisecond was put inside each bucket. If series span a longer time range, one bucket will hold more milliseconds, indicated by this value.
`buckets_count`	`bucketsCount`	`int64`	Final number of buckets. It will be same as requested, unless all series span a shorter time range.

RunSeriesTimestampBuckets.SingleSeries

SingleSeries is a columnar oriented series storage. As with RunSeriesBuckets, despite all series sharing a common first/last timestamp, millis per bucket, and buckets count, the number of values may differ if some buckets for a specific series are empty. Use bucket_indexes to detect empty buckets (same semantics as RunSeriesBuckets.SingleSeries).

Field	JSON	Type	Description
`run`	`run`	`string`	Run identifier holding this series.
`definition`	`definition`	SeriesDefinition	Full series definition
`bucket_indexes`	`bucketIndexes`	repeated `uint64`	Bucket index. Length of this array is same as for all the other arrays, if they are set. Bucket indexes show which buckets are filled, and should be used to detect empty ones.
`y_values`	`yValues`	repeated `double`	Average of values in each bucket
`counts`	`counts`	repeated `uint64`	Number of values in each bucket. Unlike the step-based RunSeriesBuckets, this is always populated: on the time axis a bucket can hold several points even at 1 ms width (steps that share a millisecond), so counts cannot be assumed to be 1.
`min_values`	`minValues`	repeated `double`	Minimum value in each bucket. Always populated (see counts).
`max_values`	`maxValues`	repeated `double`	Maximum value in each bucket. Always populated (see counts).
`last_timestamp_millis`	`lastTimestampMillis`	repeated `int64`	Timestamp of the last (youngest) point in each bucket. In the same frame as the request (see use_relative_timestamp): relative to run start when relative timestamps were requested, otherwise millis since epoch. Unlike RunSeriesBuckets, this is always populated, as it is the bucketing axis of this response.
`last_steps`	`lastSteps`	repeated `uint64`	Last step in each bucket (the step of the youngest point in the bucket). Lets the client recover step information even though the x-axis is time.
`buckets_with_nans`	`bucketsWithNans`	repeated `uint64`	Ascending indexes of buckets holding at least one NaN point. NaN/Inf points never contribute to y_values/counts/min/max — 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.

ScatterSeriesData

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition for given points. The definition kind distinguishes 2D from 3D scatters; metadata_labels carries the axis titles (“xt”/“yt”/“zt”) when the run logged them.
`points`	`points`	ScatterSeriesPoints	Compact columnar list of scatter points.
`extent`	`extent`	optional ScatterSeriesData.SeriesExtent	Present when the request set include_series_extent.

ScatterSeriesData.SeriesExtent

Extent of the whole series, independent of the request’s step selection.

Field	JSON	Type	Description
`first_step`	`firstStep`	`uint64`	First and last steps that exist for this series (exact).
`last_step`	`lastStep`	`uint64`
`points_count`	`pointsCount`	`uint64`	Approximate total step count: pre-deduplication row count, an upper bound of the number of distinct steps.
`data_points_count`	`dataPointsCount`	`uint64`	Approximate total data point (coordinate) count across all steps — pre-deduplication, so an upper bound; overwritten steps count with every logged version.

SeriesBuckets

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition for given buckets
`buckets`	`buckets`	FloatSeriesBuckets	Bucketed representation of series buckets.

SeriesPoints

Field	JSON	Type	Description
`definition`	`definition`	SeriesDefinition	Full series definition for given points
`points`	`points`	FloatSeriesPoints	Compact list of points (memory efficient).

SeriesSummaryValue

Field	JSON	Type	Description
`series_summary`	`seriesSummary`	`string`
`value`	`value`	`double`

Span

A span. The trace itself is the root span: span_id 0, parent_span_id 0, carrying the trace’s counters. Every other span belongs to a trace and names its parent.

Field	JSON	Type	Description
`trace_id`	`traceId`	`string`	Storage id of the trace: its 16 big-endian bytes in standard base64 (24 characters, padded), the same text the JSON form of a bytes field carries. Opaque to clients; pass it back to ListTraceSpans and GetSpanPayload.
`span_id`	`spanId`	`uint64`	Unique within its trace: 0 for the root, counted from 1 by the client for every other span.
`parent_span_id`	`parentSpanId`	`uint64`	Another span’s id; 0 means the span hangs off the root.
`ordinal`	`ordinal`	`uint32`	Order among siblings.
`kind`	`kind`	TraceSpanKind
`op_name`	`opName`	`string`	The agent or task name on the root, the operation name elsewhere.
`step`	`step`	optional `uint64`	The training step whose policy produced this trace. Unset for a trace anchored to the project alone.
`start_time`	`startTime`	`google.protobuf.Timestamp`
`end_time`	`endTime`	optional `google.protobuf.Timestamp`
`duration_ms`	`durationMs`	optional `uint32`
`status`	`status`	TraceStatus
`token_count`	`tokenCount`	`uint64`	Tokens this span consumed; on the root, the trace’s total as recorded by the client when it closed.
`span_count`	`spanCount`	`uint32`	Root only, recorded when the trace closed; zero elsewhere.
`iteration_count`	`iterationCount`	`uint32`
`attributes`	`attributes`	repeated Attribute	Of the names in the request’s `attribute_names`, those the span logged; each `path` is the flat attribute name.
`run`	`run`	`string`	The run the span is anchored to; empty for a project’s own spans.

SpanPayloadPart

One kind’s contiguous slice of a window.

Field	JSON	Type	Description
`payload_kind`	`payloadKind`	TracePayloadKind
`body`	`body`	`string`	Text, or for attributes a JSON object of name to value: strings, numbers and booleans as themselves, a string set as an array, a timestamp as an RFC 3339 UTC string with milliseconds (“2026-09-25T12:00:00.123Z”), a non-finite float as the proto JSON string (“NaN”, “Infinity”, “-Infinity”). Windows of one payload merge into one object.
`data_offset`	`dataOffset`	`uint32`	Where this part starts, in the kind’s units: bytes of text, or attributes for TRACE_PAYLOAD_KIND_ATTRIBUTES.
`data_length`	`dataLength`	`uint32`	The whole payload’s size in the same units, as the client stated it. The read ends there, or at the cap when this exceeds it.
`truncated`	`truncated`	`bool`	The payload’s stated size exceeds the cap, so ingestion cut it there — distinct from this response being one window, which `resume_token` reports.
`span_id`	`spanId`	`uint64`	The span this payload belongs to.

StepRange

Inclusive step range for filtering series points.

Field	JSON	Type	Description
`from_step`	`fromStep`	optional `uint64`
`to_step`	`toStep`	optional `uint64`

StepSelection

Selects range of data points to retrieve from each series. If not set, step_range with open ended first/last step is assumed.

Field	JSON	Type	Description
`step_range`	`stepRange`	StepRange oneof `selection`	Fetch exact step range from each of series. Note that both first/last step are optional though. Leaving first step uninitialized is equivalent to asking from first step ever (step 0). Leaving last step uninitialized is equivalent to last step ever (open ended). User can ask for all data points if neither end is specified. Points are returned in ascending order.
`per_series_from_the_beginning`	`perSeriesFromTheBeginning`	`int64` oneof `selection`	Number of first steps to fetch from each of series by step count. Returned points use ascending order. Number of returned points will be less if series does not have that many points, or if it has blank periods.
`per_series_from_the_end`	`perSeriesFromTheEnd`	`int64` oneof `selection`	Number of last steps to fetch from each of series by step count. Returned points use ascending order. Number of returned points will be less if series does not have that many points, or if it has blank periods.

TimestampRange

Inclusive timestamp range for filtering series points by wall-clock time. Used by ListFloatSeriesTimestampBuckets in place of StepSelection. Values are interpreted in the same frame as use_relative_timestamp on the request: when use_relative_timestamp is true, bounds are milliseconds since the run started; otherwise milliseconds since epoch. Leaving from_timestamp_millis unset means “from the first point ever”. Leaving to_timestamp_millis unset means “open ended” (latest point). Points are returned in ascending timestamp order.

Field	JSON	Type	Description
`from_timestamp_millis`	`fromTimestampMillis`	optional `int64`
`to_timestamp_millis`	`toTimestampMillis`	optional `int64`

TracePayloadKind

TASK_INPUT and FINAL_OUTPUT belong to the trace rather than to any span — the invocation’s question and its answer. Ask for them with GetSpanPayload and span_id 0, the root, which also carries the bodies of its own kind (an LLM_CALL root its prompt and completion). ATTRIBUTES is a span’s logged attributes as a JSON object (see SpanPayloadPart.body), on the root the trace’s own. INPUT and OUTPUT are the generic bodies any node may carry beside its kind-specific ones: what a function was called with and returned.

Value	Number	Description
`TRACE_PAYLOAD_KIND_UNSPECIFIED`	0
`TRACE_PAYLOAD_KIND_THOUGHT`	1
`TRACE_PAYLOAD_KIND_TOOL_INPUT`	2
`TRACE_PAYLOAD_KIND_TOOL_OUTPUT`	3
`TRACE_PAYLOAD_KIND_LLM_PROMPT`	4
`TRACE_PAYLOAD_KIND_LLM_COMPLETION`	5
`TRACE_PAYLOAD_KIND_TASK_INPUT`	6
`TRACE_PAYLOAD_KIND_FINAL_OUTPUT`	7
`TRACE_PAYLOAD_KIND_ATTRIBUTES`	8
`TRACE_PAYLOAD_KIND_INPUT`	9
`TRACE_PAYLOAD_KIND_OUTPUT`	10

TraceSpanKind

Value	Number	Description
`TRACE_SPAN_KIND_UNSPECIFIED`	0
`TRACE_SPAN_KIND_THOUGHT`	1
`TRACE_SPAN_KIND_ITERATION`	2
`TRACE_SPAN_KIND_LLM_CALL`	3
`TRACE_SPAN_KIND_TOOL_CALL`	4
`TRACE_SPAN_KIND_SUB_AGENT`	5
`TRACE_SPAN_KIND_ARTIFACT`	6
`TRACE_SPAN_KIND_FUNCTION`	7	A plain function call, the kind-neutral node a decorator wraps.
`TRACE_SPAN_KIND_SESSION_SUMMARY`	8	The childless root a session leaves when it ends, carrying the session’s own attributes (`session/reward`, `session/turn_count`) under the `session/id` its turns carry. A session may leave several; the newest is its current state.

TraceStatus

Terminal state of a trace or span, as stored. RUNNING means the open write landed and the close has not (yet) — an in-flight trace, or one whose producer died.

Value	Number	Description
`TRACE_STATUS_UNSPECIFIED`	0
`TRACE_STATUS_RUNNING`	1
`TRACE_STATUS_OK`	2
`TRACE_STATUS_ERROR`	3
`TRACE_STATUS_TRUNCATED`	4
`TRACE_STATUS_CANCELLED`	5

TracingOpName

Field	JSON	Type	Description
`op_name`	`opName`	`string`
`kind`	`kind`	TraceSpanKind	The kind of the spans logged under the name, so names can be grouped or picked by kind (an LLM call, a tool call, …) when naming the ops of a `ListSpans` search. A name logged under several kinds reports one of them.

metrana_protobuf.common.v1

AggSeriesDefinition

Identifies a pre-defined aggregated series by its grouping label set.

Field	JSON	Type	Description
`metric_name`	`metricName`	`string`
`scale`	`scale`	`string`
`group_labels`	`groupLabels`	map<`string`, `string`>	Label key=value pairs for the group-by dimensions only. Dimensions not listed here have been reduced by the aggregation.
`view`	`view`	`string`	Transformation of raw series view.

AggSeriesSummary

AggSeriesSummary holds pre-computed aggregate statistics for an aggregated series.

Field	JSON	Type	Description
`last_step`	`lastStep`	`uint64`	Step of the most recent point across all sub-series.
`last_timestamp`	`lastTimestamp`	`google.protobuf.Timestamp`	Timestamp of the most recent point.
`sum`	`sum`	optional `double`	Sum of all sub-series sums.
`count`	`count`	optional `uint64`	Sum of all sub-series point counts.
`min`	`min`	optional `double`	Minimum of all sub-series minimums.
`max`	`max`	optional `double`	Maximum of all sub-series maximums.
`std`	`std`	optional `double`	Population standard deviation across all sub-series point values.
`avg`	`avg`	optional `double`	Average of all point values
`last_count`	`lastCount`	optional `uint64`	Sum of last point sub-series point counts.
`last_min`	`lastMin`	optional `double`	Minimum sub-series value at last step.
`last_max`	`lastMax`	optional `double`	Maximum sub-series value at last step.
`last_avg`	`lastAvg`	optional `double`	Mean sub-series value at last step.
`last_std`	`lastStd`	optional `double`	Population standard deviation of sub-series values at last step.
`first_count`	`firstCount`	optional `uint64`	Sum of first point sub-series point counts.
`first_min`	`firstMin`	optional `double`	Minimum sub-series value at first step.
`first_max`	`firstMax`	optional `double`	Maximum sub-series value at first step.
`first_avg`	`firstAvg`	optional `double`	Mean sub-series value at first step.
`first_std`	`firstStd`	optional `double`	Population standard deviation of sub-series values at first step.
`last_sum`	`lastSum`	optional `double`	Sum of sub-series values at last step.

Attribute

Attribute represents snapshot value of an Attribute

Field	JSON	Type	Description
`path`	`path`	`string`	Attribute path.
`bool_value`	`boolValue`	`bool` oneof `value`	Boolean value
`string_value`	`stringValue`	`string` oneof `value`	String value
`float_value`	`floatValue`	`double` oneof `value`	Float value
`int_value`	`intValue`	`int64` oneof `value`	Integer value
`string_set_value`	`stringSetValue`	StringSet oneof `value`	Snapshot of string set
`timestamp_value`	`timestampValue`	`google.protobuf.Timestamp` oneof `value`	Timestamp value

AttributeKind

Value	Number	Description
`ATTR_KIND_UNDEFINED`	0
`ATTR_KIND_BOOL`	1
`ATTR_KIND_STRING`	2
`ATTR_KIND_FLOAT`	3
`ATTR_KIND_INT`	4
`ATTR_KIND_STRING_SET`	5
`ATTR_KIND_TIMESTAMP`	6

DensityHistogramSeriesSummary

DensityHistogramSeriesSummary is the density-kind counterpart. Densities divide the sample count out, so count/sum are structurally absent — the moments below are the normalized (count = 1) reading.

Field	JSON	Type	Description
`last_step`	`lastStep`	`uint64`	Step of the most recent histogram point.
`last_timestamp`	`lastTimestamp`	`google.protobuf.Timestamp`	Timestamp of the most recent histogram point.
`last_min`	`lastMin`	optional `double`	Sample bounds of the last histogram.
`last_max`	`lastMax`	optional `double`
`last_avg`	`lastAvg`	optional `double`	Mean of the last histogram (the normalized first moment).
`last_std`	`lastStd`	optional `double`	Population standard deviation derived from the normalized moments.

FloatSeriesBuckets

FloatSeriesBuckets is a bucketed representation of float series points for dashboard purposes. Each bucket represents a “pixel” on a panel with some width. Value “y” is an average of values for all steps in the bucket. It is essentially a sum divided by a count.

Field	JSON	Type	Description
`buckets`	`buckets`	repeated FloatSeriesBuckets.Bucket	Buckets is an ordered array, where each element represents a step range of fixed length. Number of buckets matches the response-level buckets_count. Empty buckets (no data points in the range) have y=None and stats=None.

FloatSeriesBuckets.BucketStats

BucketStats shows statistics of all step values in a given range.

Field	JSON	Type	Description
`count`	`count`	`uint64`	Count tells how many step values exist in given range.
`sum`	`sum`	`double`	Sum of all step values
`min`	`min`	`double`	Minimum step value in a range
`max`	`max`	`double`	Maximum step value in a range

FloatSeriesBuckets.Bucket

Field	JSON	Type	Description
`y`	`y`	optional `double`	Average values of all steps in a bucket. If there are no points at all, this field is not set.
`stats`	`stats`	FloatSeriesBuckets.BucketStats	Mode detailed statistics for given bucket. This object is not set if “y” is not set (due to lack of values).

FloatSeriesPoints

FloatSeriesPoints is a compact representation of float series points. Number of steps/values/timestamps must always be equal, though timestamps may be omitted entirely if configured. It is assumed it should be used to carry potentially millions of values, which is why it uses primitive types only.

Field	JSON	Type	Description
`steps`	`steps`	repeated `uint64`	Step values, always provided
`values`	`values`	repeated `double`	Value per each step, always provided.
`timestamp_millis`	`timestampMillis`	repeated `int64`	Optional timestamps if requested. If present, number of them will be equal to that of steps and values too.

HistogramSeriesPoints

HistogramSeriesPoints is a compact columnar representation of histogram series points. steps, bins, edges_idx (and timestamp_millis plus the moment arrays, when present) are index-aligned: entry i describes the histogram logged at steps[i].

Field	JSON	Type	Description
`steps`	`steps`	repeated `uint64`	Step values, always provided.
`bins`	`bins`	repeated HistogramSeriesPoints.Bins	Bin values per step, always provided.
`edges_pool`	`edgesPool`	repeated HistogramSeriesPoints.BinEdges	Bin edges are pooled: edges_pool holds each distinct edge set once and edges_idx[i] points into it. Loggers typically keep one binning for the whole run, so the pool usually holds a single entry — roughly halving the payload versus repeating edges per point.
`edges_idx`	`edgesIdx`	repeated `uint32`
`mins`	`mins`	repeated `double`	Moments of the raw pre-binning values — client-exact, or the ingestion service’s bin-approximation. Always populated for both kinds. Counting series carry raw moments (total count = sum of the point’s counts); density series carry NORMALIZED moments: sums[i] is the mean and sums_of_squares[i] is E[x²] (the count=1 reading — the count is unrecoverable from densities). An empty-sample histogram carries the exact empty sums and NaN min/max.
`maxs`	`maxs`	repeated `double`
`sums`	`sums`	repeated `double`
`sums_of_squares`	`sumsOfSquares`	repeated `double`
`timestamp_millis`	`timestampMillis`	repeated `int64`	Optional timestamps if requested. If present, number of them will be equal to that of steps.

HistogramSeriesPoints.BinEdges

One set of bin edges. Edges are strictly increasing; there is always exactly one more edge than bins.

Field	JSON	Type	Description
`edges`	`edges`	repeated `double`

HistogramSeriesPoints.Bins

Bin values of one histogram point. Exactly one of counts/densities is populated, and it is the same one for every point of a series (a series is either a counting or a density histogram, see SeriesDefinition.value_kind).

Field	JSON	Type	Description
`counts`	`counts`	repeated `uint64`
`densities`	`densities`	repeated `double`

HistogramSeriesSummary

HistogramSeriesSummary holds last-point reduced statistics of a counting histogram series, read from pre-computed header moments. Only the last point is summarized: whole-series reductions cannot be maintained idempotently under at-least-once ingestion.

Field	JSON	Type	Description
`last_step`	`lastStep`	`uint64`	Step of the most recent histogram point.
`last_timestamp`	`lastTimestamp`	`google.protobuf.Timestamp`	Timestamp of the most recent histogram point.
`last_count`	`lastCount`	optional `uint64`	Total sample count of the last histogram (sum of its bin counts).
`last_min`	`lastMin`	optional `double`	Moments of the last histogram’s raw pre-binning values — client-exact, or the ingestion service’s bin-approximation. An empty-sample histogram carries NaN min/max and zero sums.
`last_max`	`lastMax`	optional `double`
`last_sum`	`lastSum`	optional `double`
`last_avg`	`lastAvg`	optional `double`
`last_std`	`lastStd`	optional `double`

RegSeriesDefinition

Identifies a regular (raw) series by its full label set.

Field	JSON	Type	Description
`metric_name`	`metricName`	`string`
`scale`	`scale`	`string`
`labels`	`labels`	map<`string`, `string`>	Full set of label key=value pairs identifying this series.
`metadata_labels`	`metadataLabels`	map<`string`, `string`>	Non-identity display metadata (the latest non-empty set logged for the series). Never part of the series identity. Well-known keys for scatter series: “xt”/“yt”/“zt” — the axis titles (absent titles render as plain axes). Populated by ListSeriesDefinitions; discovery endpoints that return identity shape only leave it empty.

RegSeriesSummary

RegSeriesSummary holds pre-computed aggregate statistics for a regular (raw) series. Each step has a single float value.

Field	JSON	Type	Description
`last_step`	`lastStep`	`uint64`	Step of the most recent point.
`last_timestamp`	`lastTimestamp`	`google.protobuf.Timestamp`	Timestamp of the most recent point.
`first`	`first`	optional `double`	Value at the first step.
`last`	`last`	optional `double`	Value at the most recent step.
`sum`	`sum`	optional `double`	Sum of all point values.
`count`	`count`	optional `uint64`	Total number of points.
`min`	`min`	optional `double`	Minimum point value.
`max`	`max`	optional `double`	Maximum point value.
`std`	`std`	optional `double`	Population standard deviation of all point values.
`avg`	`avg`	optional `double`	Average of all point values

ScatterSeriesPoints

ScatterSeriesPoints is a compact columnar representation of scatter series points. steps, point_sets (and timestamp_millis, when present) are index-aligned: entry i is the FULL point set logged at steps[i].

Field	JSON	Type	Description
`steps`	`steps`	repeated `uint64`	Step values, always provided.
`point_sets`	`pointSets`	repeated ScatterSeriesPoints.PointSet	Point set per step, always provided.
`timestamp_millis`	`timestampMillis`	repeated `int64`	Optional timestamps if requested. If present, number of them will be equal to that of steps.

ScatterSeriesPoints.PointSet

One step’s point set as parallel coordinate arrays. xs/ys are always equal length; zs is parallel too for a 3D series and empty for a 2D one. All arrays empty is a real logged step (“no points here”) — the series definition kind, not the arrays, settles 2D vs 3D.

Field	JSON	Type
`xs`	`xs`	repeated `double`
`ys`	`ys`	repeated `double`
`zs`	`zs`	repeated `double`

ScatterSeriesSummary

ScatterSeriesSummary is the skeleton summary of a scatter series (2D and 3D alike): scatter points define no reductions, so only the position of the most recent point is reported.

Field	JSON	Type	Description
`last_step`	`lastStep`	`uint64`	Step of the most recent scatter point.
`last_timestamp`	`lastTimestamp`	`google.protobuf.Timestamp`	Timestamp of the most recent scatter point.

SeriesDefinition

A series definition. The oneof kind carries the value type structurally: float series are regular or aggregated, histogram kinds get their own variants (they share the regular shape — metric, scale, labels — and cannot be aggregated).

Field	JSON	Type	Description
`regular`	`regular`	RegSeriesDefinition oneof `kind`	Regular (raw) float series.
`aggregated`	`aggregated`	AggSeriesDefinition oneof `kind`	Pre-aggregated float series.
`histogram`	`histogram`	RegSeriesDefinition oneof `kind`	Counting histogram series.
`density_histogram`	`densityHistogram`	RegSeriesDefinition oneof `kind`	Density histogram series.
`scatter`	`scatter`	RegSeriesDefinition oneof `kind`	2D scatter series.
`scatter_3d`	`scatter3d`	RegSeriesDefinition oneof `kind`	3D scatter series.

SeriesSummary

SeriesSummary wraps one per-kind series summary; the variant mirrors SeriesDefinition.kind.

Field	JSON	Type
`regular`	`regular`	RegSeriesSummary oneof `kind`
`aggregated`	`aggregated`	AggSeriesSummary oneof `kind`
`histogram`	`histogram`	HistogramSeriesSummary oneof `kind`
`density_histogram`	`densityHistogram`	DensityHistogramSeriesSummary oneof `kind`
`scatter`	`scatter`	ScatterSeriesSummary oneof `kind`
`scatter_3d`	`scatter3d`	ScatterSeriesSummary oneof `kind`

SeriesValueKind

Value type of a series’ points.

Value	Number	Description
`SERIES_VALUE_KIND_UNDEFINED`	0
`SERIES_VALUE_KIND_FLOAT`	1	Scalar float per step.
`SERIES_VALUE_KIND_HISTOGRAM`	2	Histogram per step: bin edges + integer counts. Counts are additive, so these series support merging and count-based reductions.
`SERIES_VALUE_KIND_DENSITY_HISTOGRAM`	3	Histogram per step normalized to a probability density (numpy density=True). Sample counts are divided out, so merging and count/sum reductions are undefined; shape reductions (mean/std/pXX) remain available.
`SERIES_VALUE_KIND_SCATTER`	4	Scatter plot per step: parallel x/y coordinate arrays. A step holds the full point set — re-logging a step overwrites it (never merges), and no reductions are defined.
`SERIES_VALUE_KIND_SCATTER_3D`	5	3D scatter plot per step: as SCATTER, with a third parallel z coordinate array. Dimensionality is part of the series kind — one series is either 2D or 3D for its whole lifetime.

StringSet

StringSet represents a set of unique string values.

Field	JSON	Type	Description
`values`	`values`	repeated `string`	List of unique values in a set.