Skip to content

Query endpoints

GET/endpoints

Endpoint API · Endpoints

Get all the endpoints for the specified tenant.

Required permissionendpoint-state:read

Parameters

Name In Type Required Description
X-Tenant-ID header string (uuid) Yes Tenant ID.
pageFromKey query string No The key of the item from where to fetch a page.
pageSize query integer No The size of the page requested.
pageTotal query boolean No Whether the number of pages should be calculated and returned in the response.
sort query array of string No Defines how to sort the data.
Each item must match the pattern (^[^:]+$)|(^[^:]+:(asc|desc)$).
healthStatus query array of string No Find endpoints by health status.
Each item must be one of: bad, good, suspicious, unknown.
type query array of string No Find endpoints by type. Please note that the type securityVm is no longer used.
Each item must be one of: computer, server, securityVm.
tamperProtectionEnabled query boolean No Find endpoints by whether Tamper Protection is turned on.
tamperProtectionSupported query boolean No Find endpoints by whether Tamper Protection is supported.
lockdownStatus query array of string No Find endpoints by lockdown status. Please note that the following statuses are no longer used: creatingWhitelist, installing, registering, and starting are now reported as locking; stopping is reported as locked; and uninstalled is reported as unlocked.
Each item must be one of: creatingWhitelist, installing, locked, notInstalled, registering, starting, stopping, unavailable, uninstalled, unlocked.
overallEncryptionStatus query array of string No Find endpoints by overall encryption status.
Each item must be one of: notEncrypted, encrypted, encrypting, notSupported, suspended, notAvailable, unmanaged.
lastSeenBefore query string No Find endpoints that were last seen before the given date and time (UTC) or a duration relative to the current date and time (exclusive).
lastSeenAfter query string No Find endpoints that were last seen after the given date and time (UTC) or a duration relative to the current date and time (inclusive).
lastOsUpdateBefore query string No Find endpoints that last applied an operating system update before the given date and time (UTC) or a duration relative to the current date and time (exclusive).
lastOsUpdateAfter query string No Find endpoints that last applied an operating system update after the given date and time (UTC) or a duration relative to the current date and time (inclusive).
ids query array of string No Find endpoints with the specified IDs.
isolationStatus query string No Find endpoints by isolation status.
Must be one of: isolated, notIsolated.
hostnameContains query string No Find endpoints where the hostname contains the given string.
serialNumberContains query string No Find endpoints where the serial number contains the given string.
associatedPersonContains query string No Find endpoints where the name of the person associated with the endpoint contains the specified string.
groupNameContains query string No Find endpoints where the name of the group the endpoint is in contains the given string.
search query string No Term to search for in the specified search fields.
searchFields query array of string No List of search fields for finding the search term you enter. Defaults to all applicable fields.
Each item must be one of: hostname, groupName, associatedPersonName, ipAddresses, osName, serialNumber, tags.
ipAddresses query array of string No Find endpoints by IP addresses.
online query boolean No Find endpoints currently online.
cloud query array of string No Find endpoints that are cloud instances. You must use URL encoding.
Each item must match the pattern ^(aws|azure|gcp)|((aws|azure|gcp):([0-9a-zA-Z-_]{1,64}))|([0-9a-zA-Z-_]{1,64})$.
fields query array of string No The fields to return in a partial response.
view query string No Type of view to be returned in the response. The 'basic' view contains only ID, type, tenant and hostname fields. A 'summary' view includes the most commonly used set of fields, broadly comparable to the default columns in the Central UI, and 'full' returns all fields available. If no view is specified the default 'summary' view will be returned.
Must be one of: basic, summary, full.
assignedToGroup query boolean No Whether endpoint is assigned to a group.
groupIds query array of string (uuid) No Match endpoints by assigned group.
Must contain at most 50 items. Items must be unique.
macAddresses query array of string No Find endpoints by MAC Addresses. Can be in EUI-48 or EUI-64 format, case insensitive, colon, hyphen or dot separated, or with no separator e.g. 01:23:45:67:89:AB, 01-23-45-67-89-ab, 0123.4567.89ab, 0123456789ab, 01:23:45:67:89🆎cd:ef.
Each item must match the pattern ^([0-9a-fA-F:\-\.]){10,32}$.
includeTags query array of string No Finds endpoints with the specified tags. The tags are listed as comma separated key:value pairs.
Must contain at most 5 items. Each item must match the pattern ^[^:]{1,40}(:[^:]{0,40})?$.
excludeTags query array of string No Finds endpoints without the specified tags. The tags are listed as comma separated key:value pairs.
Must contain at most 5 items. Each item must match the pattern ^[^:]{1,40}(:[^:]{0,40})?$.
hasTags query boolean No If not set, finds endpoints that have no tags. If set, finds endpoints that have one or more tags assigned.
lastAgentUpdateBefore query string No Finds endpoints where the agent was last updated before a specified UTC date and time, or before a date relative to the current date and time.
lastAgentUpdateAfter query string No Finds endpoints where the agent was last updated after a specified UTC date and time, or after a date relative to the current date and time.

Request samples

curl -X GET "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints" -H "Authorization: Bearer <access-token>" -H "X-Tenant-ID: <tenant-id>"


import requests

response = requests.get(
    "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints",
    headers={
        "Authorization": "Bearer <access-token>",
        "X-Tenant-ID": "<tenant-id>",
    },
)
print(response.json())


$headers = @{
    "Authorization" = "Bearer <access-token>"
    "X-Tenant-ID" = "<tenant-id>"
}
Invoke-RestMethod -Method GET -Uri "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints" -Headers $headers


package main

import (
    "fmt"
    "io"
    "net/http"
)

func main() {
    req, err := http.NewRequest("GET", "https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints", nil)
    if err != nil {
        panic(err)
    }
    req.Header.Set("Authorization", "Bearer <access-token>")
    req.Header.Set("X-Tenant-ID", "<tenant-id>")

    resp, err := http.DefaultClient.Do(req)
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()

    body, _ := io.ReadAll(resp.Body)
    fmt.Println(string(body))
}


const response = await fetch("https://api-<data-region>.central.sophos.com/endpoint/v1/endpoints", {
  method: "GET",
  headers: {
    "Authorization": "Bearer <access-token>",
    "X-Tenant-ID": "<tenant-id>",
  },
});
const data = await response.json();
console.log(data);

Responses

200 — Page of endpoints. Example shows response with the 'view' parameter set to 'full'.

Response fields

itemsarray of objectrequired
List of endpoints.
Show child attributesHide child attributes
idstring (uuid)required
Unique ID for the endpoint.
typestringrequired
Endpoint type. Please note that the type securityVm is no longer used.
Must be one of: computer, server, securityVm.
tenantobject
Represents a referenced object.
Show child attributesHide child attributes
idstring (uuid)required
The ID of the referenced object.
hostnamestringrequired
Hostname of the endpoint.
healthobject
Health status of an endpoint.
Show child attributesHide child attributes
overallstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
threatsobjectrequired
Threats on the endpoint.
Show child attributesHide child attributes
statusstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
servicesobjectrequired
Status of services on the endpoint.
Show child attributesHide child attributes
statusstringrequired
Health status of an endpoint or a service running on an endpoint.
Must be one of: good, suspicious, bad, unknown.
serviceDetailsarray of objectrequired
Details of services on the endpoint.
Show child attributesHide child attributes
namestringrequired
Service name.
statusstringrequired
Status of a service on an endpoint.
Must be one of: running, stopped, missing.
osobjectrequired
OS information.
Show child attributesHide child attributes
isServerboolean
Whether the OS is a server OS.
platformstringrequired
OS platform type.
Must be one of: windows, linux, macOS.
namestringrequired
OS name as reported by the endpoint.
majorVersioninteger
OS major version.
minorVersioninteger
OS minor version.
buildinteger
OS build.
ipv4Addressesarray of string
List of IPv4 addresses.
ipv6Addressesarray of string
List of IPv6 addresses.
macAddressesarray of string
List of MAC addresses.
groupobject
Endpoint group.
Show child attributesHide child attributes
namestring
Endpoint group name.
idstring (uuid)
Unique ID for endpoint group.
groupHierarchyarray of object
List of groups in the hierarchy, starting with the group the endpoint is in and ending with the top-level group.
A single group in the endpoint group hierarchy.
Show child attributesHide child attributes
namestringrequired
Endpoint group name.
idstring (uuid)required
Unique ID for endpoint group.
parentIdstring (uuid)
Unique ID of the parent group. Omitted for the top-level group.
associatedPersonobject
Person associated with an endpoint.
Show child attributesHide child attributes
namestring
Person's name.
viaLoginstring
Person's login on the endpoint.
idstring (uuid)
Unique ID for the Person.
tamperProtectionSupportedboolean
Whether the endpoint supports Tamper Protection.
tamperProtectionEnabledboolean
Whether Tamper Protection is turned on.
assignedProductsarray of object
Products assigned to the endpoint.
Show child attributesHide child attributes
codestringrequired
Endpoint product.
Must be one of: coreAgent, interceptX, xdr, endpointProtection, deviceEncryption, mtr, ztna.
versionstringrequired
Version of a product assigned to an endpoint.
statusstring
Installation status of a product assigned to the endpoint.
Must be one of: installed, notInstalled.
packagesobject
Choice of device software available to the endpoint.
Show child attributesHide child attributes
protectionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
ztnaobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
encryptionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
deviceSoftwareobject
Choice of device software available to the endpoint.
Show child attributesHide child attributes
protectionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
ztnaobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
encryptionobject
Device software.
Show child attributesHide child attributes
assignedIdstring
The ID of the currently installed device software.
namestring
The name of the currently installed device software.
statusstring
Device software status.
Must be one of: assigned, unassigned, unlicensed, unsupported, upgradable.
availablearray of object
The available device software.
Show child attributesHide child attributes
idstring
The ID of the available device software.
namestring
The name of the available device software.
lastSeenAtstring
Date and time (UTC) when the endpoint last communicated with Sophos Central.
lastOsUpdateAtstring
Date and time (UTC) when the endpoint last applied an operating system update.
serialNumberstring
The hardware/BIOS serial number of the endpoint. Only Mac endpoints report their serial number currently.
encryptionobject
Endpoint encryption state.
Show child attributesHide child attributes
volumesarray of objectrequired
Endpoint volumes.
Endpoint volume encryption status.
Show child attributesHide child attributes
volumeIdstringrequired
Endpoint volume ID.
statusstringrequired
Endpoint volume encryption status.
Must be one of: notEncrypted, encrypted, encrypting, notSupported, suspended, unknown.
overallStatusstring
The overall encryption status of the endpoint.
Must be one of: notEncrypted, encrypted, encrypting, notSupported, suspended, notAvailable, unmanaged.
lockdownobject
Server Lockdown status.
Show child attributesHide child attributes
statusstringrequired
Server lockdown status. Please note that the following statuses are no longer used: creatingWhitelist, installing, registering, and starting are now reported as locking; stopping is reported as locked; and uninstalled is reported as unlocked.
Must be one of: creatingWhitelist, installing, locked, notInstalled, registering, starting, stopping, unavailable, uninstalled, unlocked, locking.
tagsarray of object
List of tags.
Must contain at most 15 items.
Tagging object that can be applied to multiple types of devices or other objects.
Show child attributesHide child attributes
keystringrequired
A tag key. Between 1 and 40 characters which must not include colons.
Must match the pattern ^[^:]{1,40}$.
valuestringrequired
A tag value between 0 and 40 characters which must not include colons.
Must match the pattern ^[^:]{0,40}$.
displayStringstring
A tag display string.
Must match the pattern ^([^:]{1,40}):([^:]{0,40})$.
tagOriginstring
The origin of the tag.
vendorNamestring
The name of the third-party vendor associated with the tag.
onlineboolean
Whether endpoint is currently online.
cloudobject
Endpoint cloud.
Show child attributesHide child attributes
providerstringrequired
Cloud provider in which the endpoint is running.
Must be one of: aws, azure.
instanceIdstringrequired
Unique ID for the cloud instance.
Must match the pattern ^([0-9a-zA-Z-_]{1,64}).
isolationobject
Endpoint isolation state as reported by an endpoint.
Show child attributesHide child attributes
statusstringrequired
Isolation status reported by endpoint.
Must be one of: isolated, notIsolated.
adminIsolatedboolean
Whether isolation was triggered by an admin.
selfIsolatedboolean
Whether isolation was triggered by the endpoint itself.
clonedboolean
Whether the endpoint has been cloned by another endpoint.
lastAgentUpdateAtstring
Date and time (UTC) when the agent was last successfully updated.
pagesobjectrequired
Show child attributesHide child attributes
fromKeystring
The key of the first item in the returned page.
nextKeystring
The key to use when fetching the next page.
sizeintegerrequired
The size of the page being returned.
totalinteger
(Optional) The total number of pages that exist, if pageTotal=true in the request.
itemsinteger
(Optional) The total number of items on all the pages, if pageTotal=true was passed into the request.
maxSizeintegerrequired
The maximum page size that can be requested.

Errors

Status Meaning
400 Bad request.
500 Unexpected error.

All error responses share the same shape — see the error response object.

Response examples

200

{
  "items": [
    {
      "id": "00000000-0000-0000-0000-000000000000",
      "type": "computer",
      "tenant": {
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "hostname": "string",
      "health": {
        "overall": "good",
        "threats": {
          "status": "good"
        },
        "services": {
          "status": "good",
          "serviceDetails": [
            {
              "name": "string",
              "status": "running"
            }
          ]
        }
      },
      "os": {
        "isServer": true,
        "platform": "windows",
        "name": "string",
        "majorVersion": 0,
        "minorVersion": 0,
        "build": 0
      },
      "ipv4Addresses": [
        "string"
      ],
      "ipv6Addresses": [
        "string"
      ],
      "macAddresses": [
        "string"
      ],
      "group": {
        "name": "string",
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "groupHierarchy": [
        {
          "name": "Data Team",
          "id": "7ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "parentId": "6ba7b810-9dad-11d1-80b4-00c04fd430c8"
        },
        {
          "name": "Backend Team",
          "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
          "parentId": "550e8400-e29b-41d4-a716-446655440000"
        },
        {
          "name": "Engineering",
          "id": "550e8400-e29b-41d4-a716-446655440000"
        }
      ],
      "associatedPerson": {
        "name": "string",
        "viaLogin": "string",
        "id": "00000000-0000-0000-0000-000000000000"
      },
      "tamperProtectionSupported": true,
      "tamperProtectionEnabled": true,
      "assignedProducts": [
        {
          "code": "coreAgent",
          "version": "string",
          "status": "installed"
        }
      ],
      "packages": {
        "protection": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "ztna": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "encryption": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        }
      },
      "deviceSoftware": {
        "protection": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "ztna": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        },
        "encryption": {
          "assignedId": "string",
          "name": "string",
          "status": "assigned",
          "available": [
            {
              "id": "string",
              "name": "string"
            }
          ]
        }
      },
      "lastSeenAt": "2019-09-23T12:02:01.700Z",
      "lastOsUpdateAt": "2025-02-23T12:02:01.700Z",
      "serialNumber": "P28DA81LMD5T",
      "encryption": {
        "volumes": [
          {
            "volumeId": "string",
            "status": "notEncrypted"
          }
        ],
        "overallStatus": "notEncrypted"
      },
      "lockdown": {
        "status": "creatingWhitelist"
      },
      "tags": [
        {
          "key": "string",
          "value": "string",
          "displayString": "string",
          "tagOrigin": "string",
          "vendorName": "string"
        }
      ],
      "online": true,
      "cloud": {
        "provider": "aws",
        "instanceId": "string"
      },
      "isolation": {
        "status": "isolated",
        "adminIsolated": true,
        "selfIsolated": true
      },
      "cloned": true,
      "lastAgentUpdateAt": "2019-09-23T12:02:01.700Z"
    }
  ],
  "pages": {
    "fromKey": "string",
    "nextKey": "string",
    "size": 0,
    "total": 0,
    "items": 0,
    "maxSize": 0
  }
}

See the guide for a narrative walkthrough of this API.