Skip to content
Metrana Docs

Listing resources

The resource listings walk Metrana’s hierarchy — workspace, project, then the experiments, directories and runs inside a project. They share one shape: optional filter and orderBy expressions, limit / offset paging, and a list of attributePaths to return with each item.

Workspaces

Section titled “Workspaces”

ListWorkspaces (POST /api/query/v1/workspaces:list) takes an empty request and returns every workspace the caller can read, with its organization slug and project count. It is not paged.

Projects

Section titled “Projects”

ListProjects (projects:list) lists a workspace’s projects with their run and experiment counts:

{
  "workspace": "my-workspace",
  "filter": "attr(team) == \"vision\"",
  "orderBy": "attr(sys/creation_time) DESC",
  "limit": "100"
}

Runs

Section titled “Runs”

ListRuns (runs:list) is the most capable listing: it can narrow by experiment and directory, filter and sort by attributes and series, and return series summaries alongside attributes — everything needed for a runs table in one call.

{
  "workspace": "my-workspace",
  "project": "vision",
  "experiment": "lr-sweep",
  "filter": "attr(config/optimizer) == \"adamw\" AND eval/accuracy(filter=(split=\"val\")):max >= 0.9",
  "orderBy": "eval/accuracy(filter=(split=\"val\")):max DESC",
  "attributePaths": ["config/lr", "config/batch_size", "sys/status"],
  "seriesSummaries": ["train/loss():last", "eval/accuracy(filter=(split=\"val\")):max"],
  "limit": "50",
  "offset": "0"
}

Each run comes back with its name, experiment, the requested attributes it has, and a seriesSummaries entry for each requested summary it has a value for, keyed by the summary string exactly as you sent it. A selector that matches several series of a run returns their combined value — see label resolution.

  • directoryPath restricts the listing to runs in that directory.
  • Histogram summaries and aggregate= selectors need fully specified, equality-only labels. Scatter selectors have no functions, so they cannot be summaries (use them in filter with EXISTS).

Experiments and directories

Section titled “Experiments and directories”

ListExperiments (experiments:list) and ListDirectories (directories:list) work like ListProjects, one level down. Both filter and sort by attributes only.

  • Experiments report their run count; directoryPath restricts them to one directory.
  • Directories report their run, experiment and sub-directory counts. With directoryPath set, only that directory’s direct children are listed; otherwise the top level.

Paging

Section titled “Paging”

limit defaults to 50 and may be at most 1,000; offset skips that many results. Every response includes totalCount — the number of matches before paging — so you know when to stop:

offset = 0
while True:
    page = stub.ListRuns(api_pb2.ListRunsRequest(workspace="ws", project="vision", limit=1000, offset=offset),
                         metadata=auth)
    handle(page.runs)
    offset += len(page.runs)
    if offset >= page.total_count or not page.runs:
        break

Results are consistent within a page, not across pages: runs created while you page may shift later pages. Sort by a stable key such as attr(sys/creation_time) when paging through a changing project.

System attributes

Section titled “System attributes”

Every resource carries attributes under sys/ that Metrana maintains, usable in attributePaths, filters and orderings. For runs these include:

Path Type Meaning
sys/name string Run name.
sys/id string Run id.
sys/experiment/name string Experiment name.
sys/creation_time timestamp When the run was created.
sys/modification_time timestamp When the run was last modified.
sys/status string CREATED, RUNNING, CLOSED or CRASHED.
sys/close_time timestamp When the run closed.
sys/running_time_seconds int How long the run has been running.
sys/rl/has_environments bool Whether the run logged reinforcement-learning environments.
sys/owner string The user who created the run.
sys/description string The run’s description.
sys/tags string set The run’s tags.
sys/archived bool Whether the run is archived.
sys/forking/parent_run_name, sys/forking/step string, int Fork origin, for forked runs.

To see exactly which attributes a project’s runs have, use ListAttributesDefinitions.