List endpoints

edit

Retrieves a list of hosts running Endpoint Security.

Console supports Elasticsearch APIs only. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

Request URL

edit

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

Request body

edit

A JSON object with these fields:

Name Type Description Required

paging_properties

Array

A set of page instruction Objects that contain the following:

  • page_size (number): Size of results per page. 1 to 10000.
  • page_index (number): The zero-based page of results to retrieve.

A sample value for paging_properties would be:

paging_properties: [{page_size: 20}, {page_index: 0}]

No

filters

Object

Filters to apply to the list query. It may contain the following filters as properties:

  • kql (string): A KQL string.
  • host_status (array, string): A set of agent health statuses to filter by.

Accepted health status values are:

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

No

Example requests

edit

List endpoints:

POST /api/endpoint/metadata
{
	"paging_properties": [
		{ "page_size": 10 },
		{ "page_index": 0 }
	]
}

Lists endpoints, filtered by Windows OS:

POST /api/endpoint/metadata
{
    "paging_properties": [
        { "page_size": 10 },
        { "page_index": 0 }
    ],
    "filters": {
        "kql": "united.endpoint.host.os.name : \"Windows\""
    }
}

Response code

edit
200
Indicates a successful call.

Example response

edit
{
    "hosts": [
        {
            "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
                }
            }
        }
    ],
    "request_page_index": 0,
    "request_page_size": 10,
    "total": 2
}