---
title: "List hosts with filter"
method: POST
path: "/v1/hosts/filter"
tags: ["Hosts"]
---

# List hosts with filter

`POST /v1/hosts/filter`

## Request

- Base URL: `https://help.puppet.com/api/public`
- URL: `https://help.puppet.com/api/public/v1/hosts/filter`
- Auth: API key in header `Authorization`
- TypeScript: <https://skmtc.dev/puppet/apis/puppet-comply-api/docs/v1/hosts/filter/post.ts> (a function with typed inputs; its response is checked against the schema)

Retrieve a list of all hosts with given filter.

To use this endpoint, you must have one of the following roles:
`comply-admin`
`comply-operator`
`comply-viewer`

## Query parameters

- `offset` integer
- `limit` integer

## Request body

- object
  - `environments` string[], nullable: If specified, only nodes in at least one of the given environments will be included.
  - `hostnames` string[], nullable: If specified, nodes with at least one of the hostname will be included.
  - `node_groups` string[], nullable: If specified, only nodes in at least one of the given node groups will be included.
  - `operating_systems` string[], nullable: If specified, only nodes of the given operating systems will be included. Each operating system must be specified as a string with the name and version separated by a space.

## Response `200`

HostsFilteredListResponse is the response for a list hosts request with filter.

- object
  - `data` Host[], required: Data contains list of hosts records.
    - `assessor_version` string, nullable: The assessor_version of the host.
    - `environment` string, required: The environment of the host.
    - `id` integer, required: The ID of the host.
    - `name` string, required: The name of the host.
    - `operating_system` OperatingSystem, required
      - `compatible_benchmarks` Compatiblebenchmark[], nullable: CompatibleBenchmarks for operating system.
        - `id` integer, required: The ID of the benchmark.
        - `name` string, required: The Name of the benchmark.
      - `id` integer, required: The ID of an operating system.
      - `name` string, required: The name of an operating system.
  - `limit` integer: If specified limit, you retrieve a subset of records limited to the given value..
  - `next` string, nullable: Next page value .
  - `offset` integer: Offset is the position in the dataset of a particular record. By specifying offset, you retrieve a subset of records starting with the offset value.
  - `total` integer, required: Total number of records.

## Other responses

- `default`: ErrorResponse is the default error response.

---

[API](https://skmtc.dev/puppet/apis/puppet-comply-api.md) - [All operations](https://skmtc.dev/puppet/apis/puppet-comply-api/llms.txt) - [OpenAPI document](https://skmtc.dev/puppet/apis/puppet-comply-api/revisions/0a7ac90117d7?raw)