---
title: "Search runner pools"
method: POST
path: "/runners/runner-pools/search"
tags: ["Self-Hosted Runners"]
---

# Search runner pools

`POST /runners/runner-pools/search`

Search runner pools with advanced filtering, sorting, and text search

## Query parameters

- `pageSize` integer
- `offset` integer

## Request body

- SearchRunnerPoolsRequest
  - `text` string — Free text search query, searches across pool name and labels
  - `filters` RunnerPoolFilters
    - `match` RunnerPoolMatchFilters — Matching filters (key-value pairs). Values within the same filter use OR logic, filters across different types use AND logic.
      - `name` union
        - string
        - string[]
      - `status` union
        - 'healthy' | 'partial' | 'inactive' — Overall health status of the pool
        - PoolHealthStatus[]
      - `labels` union
        - string
        - string[]
    - `created` TimestampFilters
      - `before` string, date-time — Matches when timestamp is before this date
      - `after` string, date-time — Matches when timestamp is after this date
    - `updated` TimestampFilters
      - `before` string, date-time — Matches when timestamp is before this date
      - `after` string, date-time — Matches when timestamp is after this date
  - `sort` RunnerPoolSort[] — Array of sort criteria. Multiple sort fields are applied in order.
    - `field` 'name' | 'createdAt' | 'updatedAt' | 'runnersCount' | 'assignedProjectsCount' | 'assignedWorkspaceCount' | 'poolStatus', required — Field to sort by
    - `direction` 'asc' | 'desc', required — Sort direction, either ascending (asc) or descending (desc)

## Response `200`

Runner pools matching search criteria retrieved successfully

- RunnerPool[]
  - `id` string — Unique identifier for the runner pool
  - `name` string — Name of the runner pool
  - `accountId` string — ID of the account the pool belongs to
  - `labels` string[] — Labels assigned to the runner pool
  - `description` string — Description of the runner pool
  - `runnersCount` integer — Number of runners in the pool
  - `assignedProjectsCount` integer — Number of projects assigned to this pool
  - `assignedWorkspaceCount` integer — Number of workspaces assigned to this pool
  - `assignedProjects` object[] — List of projects assigned to this pool
    - `id` string
    - `name` string
  - `assignedWorkspaces` object[] — List of workspaces assigned to this pool
    - `id` string
    - `name` string
  - `health` PoolHealth
    - `poolStatus` 'healthy' | 'partial' | 'inactive' — Overall health status of the pool
    - `statusByRunner` object — Map of runner ID to runner health status
  - `createdAt` string, date-time — Timestamp when the pool was created
  - `updatedAt` string, date-time — Timestamp when the pool was last updated

## Other responses

- `400` — Bad Request Error
- `401` — Unauthorized Error
- `403` — Insufficient permissions
- `404` — Not Found Error
- `500` — Internal Server Error

---

[API](https://skmtc.net/firefly/apis/api-gateway.md) · [All operations](https://skmtc.net/firefly/apis/api-gateway/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/firefly/api-gateway/revisions/eea119b4113f/schema)