---
title: "Search hosts using filters"
method: POST
path: "/bus/hosts"
tags: ["bus"]
---

# Search hosts using filters

`POST /bus/hosts`

Returns a filtered list of hosts based on specified criteria

## Request body

- object
  - `usabilityMode` 'usable' | 'unusable' | 'all'
  - `filterMode` 'allowed' | 'blocked' | 'all'
  - `offset` integer — The number of hosts to skip
  - `limit` integer — The maximum number of hosts to return
  - `addressContains` string — The host's net address to search for
  - `keyIn` PublicKey[]
  - `maxLastScan` string, date-time

## Response `200`

List of filtered hosts

- Host[]
  - `knownSince` string, date-time — The time the host was first seen
  - `lastAnnouncement` string, date-time — The time the host last announced itself
  - `publicKey` string — A ed25519 public key
  - `netAddress` string — The address of the host
  - `v2Settings` HostV2Settings
    - `protocolVersion` integer[] — Represents a semantic version as an array of three unsigned 8-bit integers: [major, minor, patch]
    - `release` string — Release tag of the host software
    - `walletAddress` string — The hash of a set of UnlockConditions
    - `acceptingContracts` boolean — Whether the host is accepting new contracts
    - `maxCollateral` string — An unsigned amount of Hastings, the smallest unit of currency in Sia. 1 Siacoin (SC) equals 10^24 Hastings (H).
    - `maxContractDuration` integer — Maximum allowed contract duration
    - `remainingStorage` integer — Amount of storage the host has remaining
    - `totalStorage` integer — Total amount of storage space
    - `prices` HostPrices
      - `contractPrice` string — Cost to the renter for forming, renewing, or refreshing a contract. Paid up front and covers the cost of the revision and storage proof transaction the host broadcasts at the end of the contract.
      - `collateral` string — The amount of Hastings the host will risk per byte of storage per block.
      - `storagePrice` string — Cost per byte of storage per block.
      - `ingressPrice` string — Cost per byte of data uploaded from the host
      - `egressPrice` string — Cost per byte of data downloaded from the host
      - `tipHeight` integer — The height at which the prices were last updated
      - `validUntil` string, date-time — The time at which these prices will no longer be honored by the host.
      - `signature` string, byte — A ed25519 signature
  - `interactions` HostInteractions
    - `totalScans` integer — The total number of scans performed on the host.
    - `lastScan` string, date-time — Timestamp of the last scan performed.
    - `lastScanSuccess` boolean — Indicates whether the last scan was successful.
    - `lostSectors` integer — Number of sectors lost since the last reporting period.
    - `secondToLastScanSuccess` boolean — Indicates whether the second-to-last scan was successful.
    - `uptime` string, duration — Total uptime duration of the host.
    - `downtime` string, duration — Total downtime duration of the host.
    - `successfulInteractions` number, float — The number of successful interactions with the host.
    - `failedInteractions` number, float — The number of failed interactions with the host.
  - `scanned` boolean — Whether the host has been scanned
  - `blocked` boolean — Whether the host is blocked
  - `checks` HostChecks
    - `gougingBreakdown` HostGougingBreakdown
      - `downloadErr` string — Error message related to download gouging checks.
      - `gougingErr` string — Error message related to general gouging checks.
      - `pruneErr` string — Error message related to pruning checks.
      - `uploadErr` string — Error message related to upload gouging checks.
    - `scoreBreakdown` HostScoreBreakdown
      - `age` number, float — Score contribution based on the host's age.
      - `collateral` number, float — Score contribution based on the host's collateral amount.
      - `interactions` number, float — Score contribution based on successful interactions.
      - `storageRemaining` number, float — Score contribution based on remaining storage capacity.
      - `uptime` number, float — Score contribution based on host uptime.
      - `version` number, float — Score contribution based on the host's software version.
      - `prices` number, float — Score contribution based on pricing metrics.
    - `usabilityBreakdown` HostUsabilityBreakdown
      - `blocked` boolean — Indicates if the host is blocked.
      - `offline` boolean — Indicates if the host is offline.
      - `lowMaxDuration` boolean — Indicates if the host has a low maximum contract duration.
      - `lowScore` boolean — Indicates if the host has a low score.
      - `redundantIP` boolean — Indicates if the host's IP address is redundant.
      - `gouging` boolean — Indicates if the host is gouging prices.
      - `notAcceptingContracts` boolean — Indicates if the host is not accepting new contracts.
      - `notAnnounced` boolean — Indicates if the host has not been announced on the network.
      - `notCompletingScan` boolean — Indicates if the host is failing to complete scans.
  - `storedData` integer — The amount of data stored on the host in bytes
  - `v2SiamuxAddresses` string[]

## Other responses

- `500` — Internal server error

---

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