List endpointsedit

Retrieves a list of hosts running Elastic Defend.

Request URLedit

GET <kibana host>:<port>/api/endpoint/metadata

URL query parametersedit

All parameters are optional:

Name Type Description Default

page

number

The zero-based page of results to retrieve.

0

pageSize

number

Size of results per page. 1 to 10000.

10

kuery

string

A KQL string.

hostStatuses

string[]

A set of agent health statuses to filter by.

Accepted host status values are:

  • healthy
  • unhealthy
  • offline
  • updating
  • inactive
  • unenrolled

Example requestsedit

List endpoints:

GET /api/endpoint/metadata

Lists endpoints, filtered by Windows OS:

GET /api/endpoint/metadata?kuery="united.endpoint.host.os.name : 'Windows'"

Lists endpoints, filtered by host status:

GET /api/endpoint/metadata?hostStatuses=["healthy", "updating"]

Response codeedit

200
Indicates a successful call.

Example responseedit

{
    "data": [
        {
            "host_status": "healthy",
            "metadata": {
                "@timestamp": "2021-11-24T15:47:57.432173535Z",
                "Endpoint": {
                    "capabilities": [
                        "isolation"
                    ],
                    "configuration": {
                        "isolation": false
                    },
                    "policy": {
                        "applied": {
                            "endpoint_policy_version": "2",
                            "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
                            "name": "test",
                            "status": "success",
                            "version": "3"
                        }
                    },
                    "state": {
                        "isolation": false
                    },
                    "status": "enrolled"
                },
                "agent": {
                    "build": {
                        "original": "version: 7.16.0, compiled: Tue Nov 16 16:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
                    },
                    "id": "285297c6-3bff-4b83-9a07-f3e749801123",
                    "type": "endpoint",
                    "version": "7.16.0"
                },
                "data_stream": {
                    "dataset": "endpoint.metadata",
                    "namespace": "default",
                    "type": "metrics"
                },
                "ecs": {
                    "version": "1.11.0"
                },
                "elastic": {
                    "agent": {
                        "id": "285297c6-3bff-4b83-9a07-f3e749801123"
                    }
                },
                "event": {
                    "action": "endpoint_metadata",
                    "agent_id_status": "verified",
                    "category": [
                        "host"
                    ],
                    "created": "2021-11-24T15:47:57.432173535Z",
                    "dataset": "endpoint.metadata",
                    "id": "MNtSXK/SkhEBnmgt++++++7S",
                    "ingested": "2021-11-24T15:47:58Z",
                    "kind": "metric",
                    "module": "endpoint",
                    "sequence": 400,
                    "type": [
                        "info"
                    ]
                },
                "host": {
                    "architecture": "x86_64",
                    "hostname": "david-Xubuntu",
                    "id": "0cfead88e2024bd8a27476352b5ab264",
                    "ip": [
                        "127.0.0.1",
                        "::1",
                        "10.0.2.15",
                        "fe80::2ac7:8e15:b957:2fa1"
                    ],
                    "mac": [
                        "08:00:27:e6:78:8b"
                    ],
                    "name": "david-Xubuntu",
                    "os": {
                        "Ext": {
                            "variant": "Ubuntu"
                        },
                        "family": "ubuntu",
                        "full": "Ubuntu 20.04.2",
                        "kernel": "5.8.0-59-generic #66~20.04.1-Ubuntu SMP Thu Jun 17 11:14:10 UTC 2021",
                        "name": "Linux",
                        "platform": "ubuntu",
                        "type": "linux",
                        "version": "20.04.2"
                    }
                },
                "message": "Endpoint metadata"
            },
            "policy_info": {
                "agent": {
                    "applied": {
                        "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
                        "revision": 0
                    },
                    "configured": {
                        "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
                        "revision": 3
                    }
                },
                "endpoint": {
                    "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
                    "revision": 2
                }
            }
        },
        {
            "host_status": "healthy",
            "metadata": {
                "@timestamp": "2021-11-24T15:44:31.4917849Z",
                "Endpoint": {
                    "capabilities": [
                        "isolation"
                    ],
                    "configuration": {
                        "isolation": false
                    },
                    "policy": {
                        "applied": {
                            "endpoint_policy_version": "2",
                            "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
                            "name": "test",
                            "status": "success",
                            "version": "3"
                        }
                    },
                    "state": {
                        "isolation": false
                    },
                    "status": "enrolled"
                },
                "agent": {
                    "build": {
                        "original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
                    },
                    "id": "abb8a826-6812-448c-a571-6d8269b51449",
                    "type": "endpoint",
                    "version": "7.16.0"
                },
                "data_stream": {
                    "dataset": "endpoint.metadata",
                    "namespace": "default",
                    "type": "metrics"
                },
                "ecs": {
                    "version": "1.11.0"
                },
                "elastic": {
                    "agent": {
                        "id": "abb8a826-6812-448c-a571-6d8269b51449"
                    }
                },
                "event": {
                    "action": "endpoint_metadata",
                    "agent_id_status": "verified",
                    "category": [
                        "host"
                    ],
                    "created": "2021-11-24T15:44:31.4917849Z",
                    "dataset": "endpoint.metadata",
                    "id": "MNtRc++KoKHXXwlj+++++/N9",
                    "ingested": "2021-11-24T15:44:33Z",
                    "kind": "metric",
                    "module": "endpoint",
                    "sequence": 5159,
                    "type": [
                        "info"
                    ]
                },
                "host": {
                    "architecture": "x86_64",
                    "hostname": "WinDev2104Eval",
                    "id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
                    "ip": [
                        "10.0.2.15",
                        "fe80::21a6:63d3:d70e:e3ad",
                        "127.0.0.1",
                        "::1"
                    ],
                    "mac": [
                        "08:00:27:b1:1d:5a"
                    ],
                    "name": "WinDev2104Eval",
                    "os": {
                        "Ext": {
                            "variant": "Windows 10 Enterprise Evaluation"
                        },
                        "family": "windows",
                        "full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
                        "kernel": "20H2 (10.0.19042.906)",
                        "name": "Windows",
                        "platform": "windows",
                        "type": "windows",
                        "version": "20H2 (10.0.19042.906)"
                    }
                },
                "message": "Endpoint metadata"
            },
            "policy_info": {
                "agent": {
                    "applied": {
                        "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
                        "revision": 0
                    },
                    "configured": {
                        "id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
                        "revision": 3
                    }
                },
                "endpoint": {
                    "id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
                    "revision": 2
                }
            }
        }
    ],
    "total": 2,
    "page": 0,
    "pageSize": 10
}