---
title: "List runs with optional search and tag filtering"
method: GET
path: "/api/runs/list"
tags: ["Runs"]
---

# List runs with optional search and tag filtering

`GET /api/runs/list`

## Request

- Base URL: `https://pluto-api.trainy.ai`
- URL: `https://pluto-api.trainy.ai/api/runs/list`
- Auth: HTTP bearer

Lists runs in a project with optional search using ILIKE substring matching. Supports tag filtering with OR logic (returns runs with ANY of the specified tags).

## Query parameters

- `projectName` string: Project name. Required unless `konduktorJob` is provided (which scopes to the org instead).
- `search` string: Search term for run names (substring match)
- `tags` string: Comma-separated list of tags to filter by (OR logic)
- `limit` number: Maximum number of runs to return
- `konduktorJobPrefix` string: Anchored prefix match on systemMetadata.konduktor.job_name. Accepts a full Konduktor job ID or a YAML base name (Konduktor appends a 4-char random suffix per launch). When provided, projectName becomes optional (search scopes to the org).
- `includeFieldValues` boolean, nullable: When true, attach _flatConfig and _flatSystemMetadata to each run. Off by default for lean SDK responses.
- `visibleColumns` string: JSON-encoded array of {source:'config'|'systemMetadata', key:string}. Restricts _flatConfig/_flatSystemMetadata to the listed keys. Empty array = no field values.
- `fieldFilters` string: JSON-encoded array of field-filter terms (see the FieldFilterTerm component for the structured shape and the full source/dataType/operator enums). Filters config.*/systemMetadata.* fields via the indexed run_field_values table; terms AND together. Operators (dataType-dependent): contains, does not contain, equals, is, is not, starts with, ends with, regex, is greater than/>, is less than/<, is greater than or equal to/>=, is less than or equal to/<=, is between, is not between, is before, is on or before, is after, is on or after, is any of, is none of, exists, not exists.
- `sort` string: Sort field with optional '-' (desc) or '+' (asc) prefix. Built-in: createdAt, updatedAt, name, status (snake_case accepted). heartbeat_at: last time the run logged data (computed on-demand from ClickHouse MAX(time); runs that never logged are excluded from the ordering). Config/sysmeta: config.<key>.value / systemMetadata.<key>.value. Metric: summary_metrics.<name> (LAST value). Default: createdAt desc. Invalid/unknown field → 400. For config/metric/heartbeat sorts the candidate set is capped at 10000 runs.
- `offset` number, nullable: Number of runs to skip before returning results (offset pagination). Combine with `limit` to page through results; `total` reports the full match count.
- `status` string: Comma-separated run statuses to filter by (OR within the list). One or more of: RUNNING, COMPLETED, FAILED, TERMINATED, CANCELLED. Invalid values → 400.
- `heartbeatAfter` string, date-time: ISO-8601 timestamp; keep only runs whose last logged-data time (heartbeat) is at or after this. Requires projectName.
- `heartbeatBefore` string, date-time: ISO-8601 timestamp; keep only runs whose last logged-data time (heartbeat) is at or before this (i.e. stale). Requires projectName.
- `filter` string: JSON-encoded wandb-style filter query. Supports $and/$or/$not and leaf operators (eq, $ne, $gt/$gte/$lt/$lte, $in/$nin, $regex) over: state/status, heartbeat_at, created_at/updated_at, name, tags, config.<key>, summaryMetrics.<key>.

## Response `200`

List of runs

- ListRunsResponse
  - `runs` object[], required
    - `id` number, required: Numeric run ID
    - `name` string, required: Run name
    - `number` number, nullable, required: Sequential run number within the project
    - `displayId` string, nullable, required: Human-readable display ID (e.g., 'MMP-1')
    - `projectName` string, required: Name of the project this run belongs to
    - `status` string, required: Run status
    - `tags` string[], required: Run tags
    - `createdAt` string, required: Creation timestamp
    - `_flatConfig` object: Flattened config — only present when includeFieldValues=true
    - `_flatSystemMetadata` object: Flattened systemMetadata — only present when includeFieldValues=true
  - `total` number, required: Total count of matching runs

## Other responses

- `400`: Bad request (e.g. missing both projectName and konduktorJobPrefix)
- `401`: Unauthorized

---

[API](https://skmtc.dev/trainy/apis/mlop-api.md) - [All operations](https://skmtc.dev/trainy/apis/mlop-api/llms.txt) - [OpenAPI document](https://skmtc.dev/trainy/apis/mlop-api/revisions/5d2c0b0baecb?raw)