List all hosts
Returns all hosts the authenticated user has access to, with their
ip_addresses, ports, services and interfaces included — pass
include_children=false to omit those and get a much smaller payload.
Supports pagination via limit and offset query parameters, and ordering
via group_by, order_by, and order_direction.
User API key (Bearer scp_u_...). Create in Platform > API Keys.
In: header
Query Parameters
Filter by network ID. Repeat the parameter to pass several.
Filter by specific entity IDs (for selective loading)
Filter by the service virtualizing the host. Repeat for several.
true also returns hosts nothing virtualizes. Set on its own it returns
only those — the "Not Virtualized" choice in the UI's filter.
Filter to hosts running a service with one of these names.
Filter by how the host came to exist (source.type). Repeat for several;
Inferred alone lists the hosts only a neighbour advertised.
Filter by tag IDs (returns hosts that have ANY of the specified tags)
Free-text search. Case-insensitive substring match against the host's name, hostname, sysName, chassis id 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.
Primary ordering field (used for grouping). Always sorts ASC to keep groups together.
Secondary ordering field (sorting within groups or standalone sort).
Direction for order_by field (group_by always uses ASC).
Maximum number of results to return (1-1000, default: 50). Use 0 for no limit.
Number of results to skip. Default: 0.
As-of timestamp (ISO 8601). When set, returns SCD2 state as of this instant (snapshot view) instead of live state.
true returns only hosts discovery hasn't observed within their
network's staleness window; false returns only those it has. Omit for
both. Evaluated per row against the host's own network's window.
false returns hosts with empty ip_addresses/ports/services/
interfaces. 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 Body
application/json
curl -X GET "https://example.com/api/v1/hosts"{
"data": [
{
"chassis_id_source": "Unspecified",
"created_at": "2026-01-15T10:30:00Z",
"credential_assignments": [],
"description": "Primary web server",
"display_name": "web-server-01",
"display_name_rung": "Name",
"firmware_revision": null,
"firmware_revision_source": "Unspecified",
"hidden": false,
"hostname": "web-server-01.local",
"hostname_source": "Manual",
"id": "550e8400-e29b-41d4-a716-446655440003",
"interfaces": [
{
"admin_status": "Up",
"created_at": "2026-01-15T10:30:00Z",
"display_name": "Uplink to Core Switch",
"first_discovery_id": null,
"host_id": "550e8400-e29b-41d4-a716-446655440003",
"id": "550e8400-e29b-41d4-a716-44665544000f",
"if_alias": "Uplink to Core Switch",
"if_descr": "GigabitEthernet0/1",
"if_index": 1,
"if_name": "Gi0/1",
"if_type": 6,
"ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
"ip_configured": true,
"last_discovery_id": null,
"last_seen_at": "2026-01-15T10:30:00Z",
"lineage_id": null,
"mac_address": "DE:AD:BE:EF:CA:FE",
"mac_address_source": "ArpReply",
"neighbor_candidates": [],
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"oper_status": "Up",
"speed_bps": 1000000000,
"updated_at": "2026-01-15T10:30:00Z",
"valid_from": "2026-01-15T10:30:00Z",
"valid_to": null
}
],
"ip_addresses": [
{
"created_at": "2026-01-15T10:30:00Z",
"first_discovery_id": null,
"host_id": "550e8400-e29b-41d4-a716-446655440003",
"id": "550e8400-e29b-41d4-a716-446655440005",
"ip_address": "192.168.1.100",
"last_discovery_id": null,
"last_seen_at": "2026-01-15T10:30:00Z",
"lineage_id": null,
"mac_address": "DE:AD:BE:EF:CA:FE",
"mac_address_source": "ArpReply",
"name": "eth0",
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"position": 0,
"subnet_id": "550e8400-e29b-41d4-a716-446655440004",
"updated_at": "2026-01-15T10:30:00Z",
"valid_from": "2026-01-15T10:30:00Z",
"valid_to": null
}
],
"last_seen_at": "2026-01-15T10:30:00Z",
"management_url_source": "Unspecified",
"manufacturer_source": "Unspecified",
"model_source": "Unspecified",
"name": "web-server-01",
"name_ladder": [
{
"rung": "Name",
"source": "Manual",
"value": "web-server-01"
},
{
"rung": "Hostname",
"source": "Manual",
"value": "web-server-01.local"
},
{
"rung": "SysName",
"source": null,
"value": null
},
{
"rung": "ChassisId",
"source": null,
"value": null
},
{
"rung": "Address",
"source": null,
"value": "192.168.1.100"
}
],
"name_source": "Manual",
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"ports": [
{
"created_at": "2026-01-15T10:30:00Z",
"first_discovery_id": null,
"host_id": "550e8400-e29b-41d4-a716-446655440003",
"id": "550e8400-e29b-41d4-a716-446655440006",
"last_discovery_id": null,
"last_seen_at": "2026-01-15T10:30:00Z",
"lineage_id": null,
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"number": 80,
"protocol": "Tcp",
"type": "Http",
"updated_at": "2026-01-15T10:30:00Z",
"valid_from": "2026-01-15T10:30:00Z",
"valid_to": null
}
],
"serial_number_source": "Unspecified",
"services": [
{
"bindings": [
{
"created_at": "2026-09-15T04:26:40.564137Z",
"first_discovery_id": null,
"id": "1b947f2e-f8eb-42cc-a84f-5f6d1ff85db7",
"ip_address_id": "550e8400-e29b-41d4-a716-446655440005",
"last_discovery_id": null,
"last_seen_at": "2026-09-15T04:26:40.564137Z",
"lineage_id": null,
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"port_id": "550e8400-e29b-41d4-a716-446655440006",
"service_id": "550e8400-e29b-41d4-a716-446655440007",
"type": "Port",
"updated_at": "2026-09-15T04:26:40.564137Z",
"valid_from": "2026-09-15T04:26:40.564137Z",
"valid_to": null
}
],
"created_at": "2026-01-15T10:30:00Z",
"first_discovery_id": null,
"host_id": "550e8400-e29b-41d4-a716-446655440003",
"id": "550e8400-e29b-41d4-a716-446655440007",
"last_discovery_id": null,
"last_seen_at": "2026-01-15T10:30:00Z",
"lineage_id": null,
"name": "nginx",
"network_id": "550e8400-e29b-41d4-a716-446655440002",
"position": 0,
"service_definition": "Immich",
"source": {
"type": "Manual"
},
"tags": [],
"updated_at": "2026-01-15T10:30:00Z",
"valid_from": "2026-01-15T10:30:00Z",
"valid_to": null,
"virtualization_metadata": null,
"virtualization_service_id": null
}
],
"software_revision": null,
"software_revision_source": "Unspecified",
"source": {
"type": "Manual"
},
"sys_contact_source": "Unspecified",
"sys_descr_source": "Unspecified",
"sys_location_source": "Unspecified",
"sys_name_source": "Unspecified",
"sys_object_id_source": "Unspecified",
"tags": [],
"updated_at": "2026-01-15T10:30:00Z",
"virtualization_metadata": null,
"virtualization_service_id": null
}
],
"meta": {
"api_version": 1,
"pagination": {
"has_more": true,
"limit": 50,
"offset": 0,
"total_count": 142
},
"server_version": "0.17.14"
},
"success": true,
"error": "string"
}