This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.
List endpoints
editList endpoints
editRetrieves a list of hosts running Elastic Defend.
Request URL
editGET <kibana host>:<port>/api/endpoint/metadata
URL query parameters
editAll parameters are optional:
| Name | Type | Description | Default |
|---|---|---|---|
|
number |
The zero-based page of results to retrieve. |
0 |
|
number |
Size of results per page. 1 to 10000. |
10 |
|
string |
A KQL string. |
|
|
string[] |
A set of agent health statuses to filter by. Accepted host status values are:
|
|
|
string |
Determines which field is used to sort the results. Accepted field values are:
|
|
|
string |
Determines the sort order, which can be |
|
Example requests
editList 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 code
edit-
200 - Indicates a successful call.
Example response
edit{
"data": [
{
"host_status": "healthy",
"last_checkin": "2023-07-04T15:47:57.432Z",
"metadata": {
"@timestamp": "2023-07-04T15: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": "2023-07-04T15:47:57.432173535Z",
"dataset": "endpoint.metadata",
"id": "MNtSXK/SkhEBnmgt++++++7S",
"ingested": "2023-07-04T15: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",
"last_checkin": "2023-07-04T15:44:31.491Z",
"metadata": {
"@timestamp": "2023-07-04T15: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": "2023-07-04T15:44:31.4917849Z",
"dataset": "endpoint.metadata",
"id": "MNtRc++KoKHXXwlj+++++/N9",
"ingested": "2023-07-04T15: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,
"sortField": "enrolled_at",
"sortDirection": "desc"
}