RPCs

Service is part-sync/part async. Validation part should be synchronous and user should know immediately if operation will fail. If it was accepted, it means it will eventually be processed.

CreateRun

CreateRun creates a new run. Basic metadata is created synchronously, but run is marked as fully ready for queries asynchronously. Nevertheless, clients can start sending metrics to newly created run right after this call finishes.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/CreateRun (unary)
• REST: POST /api/ingest/v1/runs
• Request: CreateRunRequest
• Response: CreateRunResponse

CreateRunRequest

CreateRunRequest is a request for CreateRun method

Field	JSON	Type	Description
run	run	Run	Definition of a run to create, must be provided.
create_project_if_missing	createProjectIfMissing	bool	If project does not exist, it will be created.
aggregation_rules	aggregationRules	repeated AggregationRule	Aggregation rules for this run. Rules declare how series should be aggregated into derived series by the ingestion worker.

CreateRunResponse

CreateRunResponse is a response for CreateRun method.

Field	JSON	Type	Description
operation_id	operationId	string	Operation ID assigned to this operation. While basic run metadata is created synchronously during call, certain attributes/series are created asynchronously if Run is forked from the other.

InitializeRunLogging

InitializeRunLogging ensures run instance is created, and logger is initialized. Server notifies logger when initializing finishes, finally returns last step for non-rl series, and last rl step per environment. Clients should switch to UpdateRunsStream. Server closes connection after sending last InitializeRunLoggingResponse.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/InitializeRunLogging (server streaming)
• REST: not available — gRPC only
• Request: InitializeRunLoggingRequest
• Response: stream of InitializeRunLoggingResponse

InitializeRunLoggingRequest

Field	JSON	Type	Description
run	run	Run	Definition of a run to create, must be provided.
create_project_if_missing	createProjectIfMissing	bool	If project does not exist, it will be created.
aggregation_rules	aggregationRules	repeated AggregationRule	Aggregation rules for this run. Rules declare how series should be aggregated into derived series by the ingestion worker.
logger_id	loggerId	uint64	Logger identifier, should be ideally unique between loggers writing to the same run.
resume_policy	resumePolicy	ResumePolicy	See ResumePolicy.

InitializeRunLoggingResponse

Field	JSON	Type	Description
initialized_run	initializedRun	InitializeRunLoggingResponse.InitializedRun oneof msg
last_logged_steps	lastLoggedSteps	InitializeRunLoggingResponse.LastLoggedSteps oneof msg
env_statuses	envStatuses	InitializeRunLoggingResponse.EnvStatuses oneof msg
rl_family_declarations	rlFamilyDeclarations	InitializeRunLoggingResponse.RlFamilyDeclarations oneof msg

InitializeRunLoggingResponse.InitializedRun

InitializedRun is the first message client will receive, informing if run was initialized just now, or if it existed before.

Field	JSON	Type	Description
created	created	bool	Flag indicates if run was created during this initialization. It is false if it already existed before.
run_id	runId	bytes	Run ID to be used in UpdateRunStream
orchestration_identifier	orchestrationIdentifier	optional string	Orchestration identifier stored on the run (set at creation from the creating client’s request). Unset when the run was created by a client that pre-dates the feature. When created is false, clients compare this against their own identifier to distinguish a sibling process of the same job launch (resume) from a stale run with a reused name (error under the Never resume strategy).
creation_time	creationTime	optional google.protobuf.Timestamp	Time the run was created. Mirrors the REST 409 contract so clients can surface when the conflicting run came into existence.

InitializeRunLoggingResponse.LastLoggedSteps

LastLoggedSteps contains last steps for non-RL series. Logger can use it to provide information to a client or use for step autoincrement. Last logged steps are sent after InitializedRun. If run has no non-rl series, it will send single LastLoggedSteps message with empty series and is_last = true.

Field	JSON	Type	Description
series	series	repeated InitializeRunLoggingResponse.LastLoggedSteps.SeriesInfo
is_last	isLast	bool

InitializeRunLoggingResponse.LastLoggedSteps.SeriesInfo

Field	JSON	Type	Description
metric_name	metricName	string
scale	scale	string
flat_labels	flatLabels	string
ordering	ordering	OrderingMode
last_step	lastStep	uint64
value_kind	valueKind	SeriesValueKind	Value kind of the stored series, read from the header flags. Lets a resuming logger reject kind-mixing at the log call instead of the worker silently dropping mismatched writes. UNDEFINED (older server) safely means float — nothing older can have logged histograms.

InitializeRunLoggingResponse.RlFamilyDeclarations

RlFamilyDeclarations lists the run’s RL series families (one entry per (metric, scale)), read from the environment metric definitions’ all-envs union. Lets a resuming logger enforce family uniformity (label key set, value kind, ordering, episodic mode) at the log call for RL metrics too, instead of the worker silently dropping divergent series. Sent after LastLoggedSteps and BEFORE EnvStatuses, so clients that complete the handshake on EnvStatuses { is_last: true } never miss it; older clients ignore the unknown message. A run with no RL families sends nothing of this kind.

Field	JSON	Type	Description
families	families	repeated InitializeRunLoggingResponse.RlFamilyDeclarations.RlFamilyDeclaration
is_last	isLast	bool

InitializeRunLoggingResponse.RlFamilyDeclarations.RlFamilyDeclaration

Field	JSON	Type	Description
metric_name	metricName	string
scale	scale	string
label_key_set	labelKeySet	string	Sorted label key names joined with ‘&’ (e.g. “host&worker”); empty for label-less families.
ordering	ordering	OrderingMode
value_kind	valueKind	SeriesValueKind
episodic	episodic	bool	Whether the family’s series carry real episodes.

InitializeRunLoggingResponse.EnvStatuses

EnvStatuses contains last rl step / last episode per each environment. Messages of this kind are sent after LastLoggedSteps. If run has no rl series, it will send single EnvStatuses message with empty envs and is_last = true.

Field	JSON	Type	Description
envs	envs	repeated InitializeRunLoggingResponse.EnvStatuses.EnvState
is_last	isLast	bool

InitializeRunLoggingResponse.EnvStatuses.EnvState

Field	JSON	Type	Description
env_name	envName	string
last_rl_step	lastRlStep	uint64
last_episode	lastEpisode	uint64

UpdateRuns

UpdateRuns enqueues run updates (Series and attributes), data will be available for queries after ingestion system completes processing this update.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/UpdateRuns (unary)
• REST: POST /api/ingest/v1/runs:update
• Request: UpdateRunsRequest
• Response: UpdateRunsResponse

UpdateRunsRequest

UpdateRunsRequest is a request for UpdateRuns method.

Field	JSON	Type	Description
logger_id	loggerId	uint64	Logger ID of the worker process sending data. It does not need to be unique across workers, because it is assumed that workers are contributing to different series and attributes. But it must be different between worker restarts, as backend uses this to detect data duplication.
run_updates	runUpdates	repeated UpdateRunsRequest.RunUpdate	Runs to update, all in one workspace: the request is metered and paced against that workspace’s limits as a whole.
logger_session_id	loggerSessionId	uint64	Logger process session plus a per-session message counter, used by the ingestion workers to drop re-sent messages before metering usage. See UpdateRunRequest.logger_session_id / sequence_number; the same contract applies here for unary callers that want replay protection. If logger_session_id is 0, then message is unsequenced.
sequence_number	sequenceNumber	uint64

UpdateRunsRequest.RunUpdate

RunUpdate represents updates for single run.

Field	JSON	Type	Description
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.
workspace	workspace	string	Name of a workspace where run is.
project	project	string	Name of a project where run is.
run_name	runName	string	Name of a run within a project.
attributes	attributes	repeated AttributeUpdate	List of attribute updates.
env_attr_updates	envAttrUpdates	repeated EnvAttrUpdates	List of RL environment attribute updates.
series	series	repeated SeriesUpdate	List of series updates.
histogram_series	histogramSeries	repeated HistogramSeriesUpdate	List of histogram series updates.
scatter_series	scatterSeries	repeated ScatterSeriesUpdate	List of scatter series updates.
rl_series	rlSeries	repeated RLSeriesUpdate	List of RL series updates.
series_declarations	seriesDeclarations	repeated SeriesDeclaration	Reusable list of series declarations (generic and RL). Field only allowed in streaming requests!
streaming_series	streamingSeries	repeated StreamingSeriesUpdate	List of series updates - allowed only in streaming update runs.
streaming_rl_series	streamingRlSeries	repeated StreamingRLSeriesUpdate	List of RL series updates - allowed only in streaming update runs.
close_run	closeRun	CloseRun	If specified, then this update will be the last processed. Run will be closed, sys/status will be set accordingly.

UpdateRunsResponse

UpdateRunsResponse is a response for UpdateRuns method.

Field	JSON	Type	Description
operation_id	operationId	string	Operation ID assigned to this operation. Once attributes and series are updated, operation is considered as completed.
write_limit_bytes_per_second	writeLimitBytesPerSecond	optional uint64	The write rate the request was metered against: the smaller of the workspace’s and its organization’s limit, in bytes per second. Unset when neither is limited. Keep a single request within one second of it.
pacing_delay_ms	pacingDelayMs	uint32	How long the server held this request so that it fit under the write rate, in milliseconds. Nonzero means the tenant is at its limit: send smaller requests until it reads zero again.

UpdateRunStream

UpdateRunStream is a streaming version of UpdateRuns. After ensuring run exists, client can connect using this method. Session is maintained until error, disconnection, or until client sends CloseRun message. Guarantees:

• Each UpdateRunRequest will receive UpdateRunResponse, ordered.

• If any UpdateRunRequest fails, subsequent also fail.

• All specific series updates (including RL) will be accepted in order. It is possible that some requests will be enqueued partially though. Client should keep retrying same request in next stream session to achieve guarantee of delivery (at least once principle).

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/UpdateRunStream (bidirectional streaming)

• REST: not available — gRPC only

• Request: stream of UpdateRunRequest

• Response: stream of UpdateRunResponse

UpdateRunRequest

UpdateRunRequest is a request for UpdateRun streaming method.

Field	JSON	Type	Description
run_id	runId	bytes	Run identifier
logger_id	loggerId	uint64	Logger ID, must be same used as in InitializeRunLogging.
attributes	attributes	repeated AttributeUpdate	List of attribute updates.
env_attr_updates	envAttrUpdates	repeated EnvAttrUpdates	List of RL environment attribute updates.
series_declarations	seriesDeclarations	repeated SeriesDeclaration	Reusable list of series declarations (generic and RL).
series	series	repeated StreamingSeriesUpdate	List of series updates.
histogram_series	histogramSeries	repeated StreamingHistogramSeriesUpdate	List of histogram series updates.
scatter_series	scatterSeries	repeated StreamingScatterSeriesUpdate	List of scatter series updates.
rl_series	rlSeries	repeated StreamingRLSeriesUpdate	List of RL series updates.
close_run	closeRun	CloseRun	If specified, then this update will be the last processed. Server will disconnect logger after processing this request. If this was the last logger, run will move to CLOSED status.
logger_session_id	loggerSessionId	uint64	Random id drawn once per logger process. Together with logger_id it scopes sequence_number; a restarted process starts a new session and its counter from scratch.
sequence_number	sequenceNumber	uint64	Strictly increasing per (logger_id, logger_session_id) in the order the requests are first sent; a retried send carries the same number. The ingestion workers keep the last number seen per session and drop any request that does not advance it: the data was already processed and metered. Gaps are fine. Zero (on logger_id or logger_session_id) marks the request as unsequenced and it is always processed; the logger sends its empty keepalives and its re-sent declaration sets that way. Packing: the counter in bits 8..62 (counter << 8), the low byte zero (the server uses it for its own size splits) and the top bit clear; anything else is INVALID_ARGUMENT.

UpdateRunResponse

UpdateRunResponse is a response for UpdateRun streaming method.

Field	JSON	Type	Description
operation_id	operationId	string	Operation ID assigned to this operation. Once attributes and series are updated, operation is considered as completed.
write_limit_bytes_per_second	writeLimitBytesPerSecond	optional uint64	The write rate the message was metered against: the smaller of the workspace’s and its organization’s limit, in bytes per second. Unset when neither is limited. Keep a single message within one second of it.
pacing_delay_ms	pacingDelayMs	uint32	How long the server held this message so that it fit under the write rate, in milliseconds. Nonzero means the tenant is at its limit: send smaller messages until it reads zero again.

UpdateTraces

UpdateTraces enqueues agentic trace updates (trace/span open and close, with the bodies a span produced). Traces ride their own Kafka topic, so this is a separate RPC rather than another field on UpdateRuns: a payload message is vastly larger than a metric point and must not head-of-line block metric ingestion.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/UpdateTraces (unary)
• REST: POST /api/ingest/v1/traces:update
• Request: UpdateTracesRequest
• Response: UpdateTracesResponse

UpdateTracesRequest

UpdateTracesRequest is a request for UpdateTraces method.

Field	JSON	Type	Description
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.
workspace	workspace	string	Name of a workspace where run is.
project	project	string	Name of a project where run is.
run_name	runName	optional string	Name of a run within a project. Unset anchors the traces to the project alone (inference traces).
trace_updates	traceUpdates	repeated TraceUpdate	Trace structure updates, processed in order. Each update’s identity.run_id may be left empty when run_name is set — the service fills it in — and when set must be that run’s id.
logger_id	loggerId	uint64	Writer identity and replay protection, as on UpdateRunRequest: the tracer process’s id, a session drawn once per process and a counter strictly increasing within the session, stamped when the request is built so a re-sent request carries the same number. The trace workers keep the last number seen per (logger_id, logger_session_id) and drop a request that does not advance it: its data was already stored and metered. Gaps are fine. Zero on logger_id or logger_session_id marks the request as unsequenced and it is always processed. sequence_number packing: the counter in bits 8..62 (counter << 8), the low byte zero (the server uses it for its own size splits) and the top bit clear; anything else is INVALID_ARGUMENT.
logger_session_id	loggerSessionId	uint64
sequence_number	sequenceNumber	uint64

UpdateTracesResponse

UpdateTracesResponse is a response for UpdateTraces method.

Field	JSON	Type	Description
operation_id	operationId	string	Operation ID assigned to this operation.
write_limit_bytes_per_second	writeLimitBytesPerSecond	optional uint64	The write rate the request was metered against: the smaller of the workspace’s and its organization’s limit, in bytes per second. Unset when neither is limited. Keep a single request within one second of it.
pacing_delay_ms	pacingDelayMs	uint32	How long the server held this request so that it fit under the write rate, in milliseconds. Nonzero means the tenant is at its limit: send smaller requests until it reads zero again.

UpdateTracesStream

UpdateTracesStream is the streaming form of UpdateTraces: a client sends requests without waiting for each acknowledgment, and receives one response per request, in order.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/UpdateTracesStream (bidirectional streaming)
• REST: not available — gRPC only
• Request: stream of UpdateTracesRequest
• Response: stream of UpdateTracesResponse

CheckOpStatuses

CheckOpStatuses checks if enqueued operation are completed or not yet.

• gRPC: /metrana_protobuf.ingestion.v1.svc.IngestService/CheckOpStatuses (unary)
• REST: POST /api/ingest/v1/operations:check
• Request: CheckOpStatusesRequest
• Response: CheckOpStatusesResponse

CheckOpStatusesRequest

CheckOpStatusesRequest is a request for CheckOpStatuses method.

Field	JSON	Type	Description
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.
workspace	workspace	string	Workspace for which operations were submitted
project	project	string	Project for which operations were submitted
operation_ids	operationIds	repeated string	List of operations to check

CheckOpStatusesResponse

CheckOpStatusesResponse is a response for CheckOpStatuses method.

Field	JSON	Type	Description
operation_statuses	operationStatuses	map<string, bool>	Operation completeness flags