SCscanopy
Hosts
internal

List host field values

Changed on

Every distinct value of one Host field across the Hosts the caller can list, with how many hold each. Takes the list's filters; ignores pagination, search and ordering.

get/api/v1/hosts/field-values/{field}

Request

  • Base URL
    https://app.scanopy.net
  • URL
    https://app.scanopy.net/api/v1/hosts/field-values/{field}
  • Auth
    • API key in header Authorization
    • or API key in cookie session_id

Path parameters

field'created_at' | 'name' | 'hostname' | 'updated_at' | 'virtualized_by' | 'site_id' | 'interface_ip' | 'last_seen_at' | 'mac_address' | 'source' | 'manufacturer' | 'model' | 'sys_location' | 'os_family' required

Fields that hosts can be ordered/grouped by.

The field whose values to count

Query parameters

site_idsstring[] nullable

Filter by site ID. Repeat the parameter to pass several.

idsstring[] nullable

Filter by specific entity IDs (for selective loading)

virtualization_service_idsstring[] nullable

Filter by the service virtualizing the host. Repeat for several.

virtualization_service_namesstring[] nullable

Filter by the name of the service virtualizing the host, the value "Virtualized By" groups on. Repeat for several.

include_unvirtualizedboolean nullable

true also returns hosts nothing virtualizes. Set on its own it returns only those — the "Not Virtualized" choice in the UI's filter.

service_namesstring[] nullable

Filter to hosts running a service with one of these names.

sourcesEntitySourceDiscriminants[] nullable

Filter by how the host came to exist (source.type). Repeat for several; Inferred alone lists the hosts only a neighbour advertised.

manufacturersstring[] nullable

Filter by hardware manufacturer. Repeat for several.

modelsstring[] nullable

Filter by hardware model. Repeat for several.

sys_locationsstring[] nullable

Filter by SNMP sysLocation. Repeat for several.

os_familiesHostOsFamily[] nullable

Filter by operating system family. Repeat for several.

credential_idsstring[] nullable

Filter to hosts assigned one of these credentials. Repeat for several.

tag_idsstring[] nullable

Filter by tag IDs (returns hosts that have ANY of the specified tags)

tag_setsstring[] nullable

Tag sets the host must hold one tag from each of. Each entry is a comma-separated list of tag ids; a host matches when it holds at least one tag of every entry. One entry per tag group the list is filtered by.

searchstring nullable

Free-text search. Case-insensitive substring match against the host's name, hostname, sysName, chassis id, serial number, asset tag and description, and against its IP addresses and the names of services running on it.

sysName and chassis id are in there because they are rungs of the title ladder: a host with no name of its own is shown under one of them, and a title you can read but cannot search for is a dead end.

group_by'created_at' | 'name' | 'hostname' | 'updated_at' | 'virtualized_by' | 'site_id' | 'interface_ip' | 'last_seen_at' | 'mac_address' | 'source' | 'manufacturer' | 'model' | 'sys_location' | 'os_family'

Fields that hosts can be ordered/grouped by.

Primary ordering field (used for grouping). Always sorts ASC to keep groups together.

order_by'created_at' | 'name' | 'hostname' | 'updated_at' | 'virtualized_by' | 'site_id' | 'interface_ip' | 'last_seen_at' | 'mac_address' | 'source' | 'manufacturer' | 'model' | 'sys_location' | 'os_family'

Fields that hosts can be ordered/grouped by.

Secondary ordering field (sorting within groups or standalone sort).

group_by_tag_groupstring uuid nullable

Group by the tag each row holds from this tag group, in the group's tag order. Takes the place of group_by.

order_by_tag_groupstring uuid nullable

Sort by the position of the tag each row holds from this tag group. Takes the place of order_by.

order_direction'asc' | 'desc'

Direction for ORDER BY clauses.

Direction for order_by field (group_by always uses ASC).

limitinteger nullable

Maximum number of results to return (1-1000, default: 50). Use 0 for no limit.

offsetinteger nullable

Number of results to skip. Default: 0.

atstring date-time nullable

As-of timestamp (ISO 8601). When set, returns SCD2 state as of this instant (snapshot view) instead of live state.

staleboolean nullable

true returns only hosts discovery hasn't observed within their site's staleness window; false returns only those it has. Omit for both. Evaluated per row against the host's own site's window.

include_childrenboolean nullable

false returns hosts with empty ports/services/interfaces. ip_addresses is always populated: the host's title can come from its address. The children dominate the payload, so callers that only need host identity — name pickers, id→name lookups, counts — should pass false. Defaults to true, so existing callers are unaffected.

Response

Distinct values and their Host counts

errorstring nullable

Not sent on a successful response. Failure messages arrive in an ApiErrorResponse.

successboolean required

Always true on a successful response.

Example response

{
  "meta": {
    "api_version": 1,
    "server_version": "0.19.4"
  }
}

Changes