Overview

The Query API is the read side of Metrana. It lists workspaces, projects, experiments, directories and runs; finds out which attributes and metrics exist; and returns attribute values, series summaries and series points — raw, bucketed for charts, or aggregated across reinforcement-learning environments — plus agentic traces. The portal and the Python SDK’s QueryClient are built on it.

Endpoints

Transport	Address	Notes
gRPC	app.metrana.ai:443 (TLS)	Service metrana_protobuf.query.v1.svc.QueryService. gRPC-Web is also accepted.
REST	https://app.metrana.ai/api/query/v1/<resource>:<verb>	JSON over HTTP POST, for example POST /api/query/v1/runs:list.

A self-hosted deployment uses its own host. Every RPC is available on both transports. See Transports and encoding for the JSON mapping.

Authentication

Send an access token as authorization: Bearer <token>, obtained by exchanging your API token as described in Authentication. Any role in a workspace — viewer included — can read it. Requests without a token are served as anonymous and can read public workspaces only.

How requests address data

Every request names a workspace (plus organization if the name is shared across organizations) and, below the workspace level, a project. Runs, experiments and environments are addressed by name.

What you ask for is expressed partly in fields and partly in short expressions of the query language:

attr(config/optimizer) == "adamw" AND train/loss(scale=ML_STEP):last < 0.5     ← a run filter
train/loss(filter=(gpu="0")):min                                                ← a series summary
train/loss(filter=(gpu IN ["0", "1"])) | group_by(keys=[host], reducer=avg)     ← a series query

The RPCs by task

Task	RPCs	Guide
List workspaces, projects, experiments, directories, runs	ListWorkspaces, ListProjects, ListExperiments, ListDirectories, ListRuns	Listing resources
Find which attributes, metrics and series exist	ListAttributesDefinitions, ListMetricDefinitions, ListSeriesDefinitions, ListSeriesLabelValues and their Browse… forms	Discovering data
Read attribute values	ListAttributes, BrowseAttributes	Discovering data
Read series summaries and points	ListSeriesSummaries, ListFloatSeries, ListFloatSeriesBuckets, ListFloatSeriesTimestampBuckets, ListHistogramSeries, ListScatterSeries	Reading series
Read reinforcement-learning environments	GetRLInfo, ListRLEnvironments, ListRLEnvironmentFloatSeriesBuckets, AggregateRLEnvironmentSeries, RL attribute and metric discovery	RL environments
Read agentic traces	ListSpans, ListTraceSpans, GetSpanPayload, ListTracingOpNames, ListTracingAttributeDefinitions	Agentic traces

Every RPC’s fields are documented in the RPC reference, grouped the same way: resource listing, discovery, attributes, series summaries, series points and agentic traces.

Pagination

Two styles are used, and each RPC’s reference says which:

• Offset pagination — resource listings (ListRuns, ListProjects, …) take limit and offset and return totalCount.
• Resume tokens — discovery, attribute and series reads return a resumeToken when more results remain. Send the same request again with that token to get the next page; every other field must stay the same. No token in the response means you have everything.

Freshness

Data becomes readable a moment after the Ingestion API accepts it. Summaries and counts may briefly lag the newest points.