{"type":"api","title":"Filter endpoint agents","meta":{"id":"/apps/pubhub/media/000-v7-apis/5b3454a4300b838cc17f7b2cdc0690fdd15058d5/8ebf57c6-5c11-32a6-b382-0c79fa6e8efc","info":{"description":"Manage ThousandEyes Endpoint Agents using this API. \n\nFor more information about Endpoint Agents, see [Endpoint Agents](https://docs.thousandeyes.com/product-documentation/global-vantage-points/endpoint-agents).","title":"Endpoint Agents API","version":"7.0.34"},"security":[{"BearerAuth":[]}],"tags":[{"name":"Endpoint Agents"},{"name":"Endpoint Agents Transfer"}],"openapi":"3.0.1","servers":[{"description":"ThousandEyes API production URL","url":"https://api.thousandeyes.com/v7"}],"securitySchemes":{"BearerAuth":{"description":"Bearer authentication token","scheme":"bearer","type":"http"}}},"spec":{"description":"Retrieves a list of endpoint agents within the specified account group that match the specified filters.\n\nIf no agents meet the filter criteria, the API returns an empty array.\n","operationId":"filterEndpointAgents","parameters":[{"description":"(Optional) Maximum number of objects to return.","in":"query","name":"max","schema":{"example":5,"type":"integer"}},{"description":"(Optional) Opaque cursor used for pagination. Clients should use `next` value from `_links` instead of this parameter.","in":"query","name":"cursor","schema":{"type":"string","example":null}},{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint. Note that you must be assigned to the target account group. Specifying this parameter without being assigned to the target account group will result in an error response.","in":"query","name":"aid","required":false,"schema":{"example":"1234","type":"string"}},{"description":"This optional parameter allows you to control the expansion of test resources associated with the agent. By default, no expansion occurs when this query parameter is omitted.\nTo expand the \"clients\" resource, include the query parameter `?expand=clients`.\n\nFor multiple expansions, you have two options:\n \n* Separate the values with commas. For example, `?expandAgent=clients,tasks`.\n* Specify the parameter multiple times. For example, `?expandAgent=clients&expandAgent=tasks`.\n\nThis parameter offers flexibility for users to customize the expansion of specific resources related to the agent.\n","example":["clients","vpnProfiles","networkInterfaceProfiles"],"explode":false,"in":"query","name":"expand","required":false,"schema":{"items":{"enum":["clients","vpnProfiles","networkInterfaceProfiles"],"type":"string","$$ref":"#/components/schemas/ExpandEndpointAgentOptions"},"type":"array"},"style":"form"},{"description":"When requesting entities, set to `true` if you want to see deleted entities.","example":false,"explode":true,"in":"query","name":"includeDeleted","required":false,"schema":{"type":"boolean"},"style":"form"}],"requestBody":{"content":{"application/json":{"schema":{"description":"Parameters for filtering a list of agents.","properties":{"searchFilters":{"properties":{"id":{"description":"Returns only agents that are an exact match of the provided identifiers.","items":{"description":"Unique ID of endpoint agent, from `/endpoint/agents` endpoint.","example":"861b7557-cd57-4bbb-b648-00bddf88ef49","format":"uuid","readOnly":true,"type":"string","$$ref":"#/components/schemas/EndpointAgentId"},"type":"array"},"agentName":{"description":"Returns only agents with the given name. \nThis is an exact match only.\n","items":{"description":"Returns only agents with the specified name. \nThis is an exact match only.\n","example":"myagent-1234","type":"string","$$ref":"#/components/schemas/AgentName"},"type":"array"},"computerName":{"description":"Returns only agents with the given computer name.\nThis is an exact match only.\n","items":{"description":"Returns only agents with the specified computer name.\nThis is an exact match only.\n","example":"DESKTOP-45AE8","type":"string","$$ref":"#/components/schemas/ComputerName"},"type":"array"},"username":{"description":"Returns only agents that have at least one user with a name.\nstarting with the provided string. This is a case-insensitive prefix match.\n","example":["picard"],"items":{"type":"string"},"type":"array"},"platform":{"description":"Filter on the platform on which the agent is running.\n","items":{"description":"OS platform types. Platform \"linux\" was recently renamed to \"roomos\".","enum":["windows","roomos","phoneos","elux","linux","mac","unknown"],"example":"mac","type":"string","$$ref":"#/components/schemas/Platform"},"type":"array"},"osVersion":{"description":"Case-insensitive prefix filter on the OS version.","items":{"example":"Version 10.15.2","type":"string"},"type":"array"},"locationCountryISO":{"description":"Filter using the ISO country code of the location.\n","items":{"example":"FR","type":"string"},"type":"array"},"locationSubdivision1Code":{"description":"Filter using the code for the first level administrative division within \nthe country. In US/Canada this is the State, in UK it's the country e.g. `ENG`\n","items":{"example":"ENG","type":"string"},"type":"array"},"locationCity":{"description":"This is a prefix match on the city name field. The endpoint expects this to contain the \nname of the city in English. e.g. 'Paris' or ''\n","items":{"example":"Paris","type":"string"},"type":"array"},"licenseType":{"description":"Filter on the agent's license type\n","items":{"enum":["essentials","advantage","embedded"],"example":"essentials","type":"string","$$ref":"#/components/schemas/AgentLicenseType"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/AgentSearchFilters"},"thresholdFilter":{"description":"All filters are applied based on the conditional operator (and/or).","properties":{"filters":{"items":{"description":"The metric is filtered based on the threshold value and operator provided.","properties":{"name":{"enum":["last-seen-ms"],"type":"string"},"value":{"description":"The threshold value.","format":"double","type":"number"},"operator":{"enum":["gte","lte"],"example":"gte","type":"string","$$ref":"#/components/schemas/ThresholdFilterOperator"}},"type":"object","$$ref":"#/components/schemas/AgentThresholdFilter"},"type":"array"},"conditionalOperator":{"enum":["and","or"],"example":"and","type":"string","$$ref":"#/components/schemas/ConditionalOperator"}},"type":"object","$$ref":"#/components/schemas/AgentThresholdFilters"},"searchSort":{"items":{"properties":{"sort":{"enum":["platform","osVersion","name","userName","city"],"type":"string","$$ref":"#/components/schemas/AgentSearchSortKey"},"order":{"description":"Parameter indicates the ascending/descending order of the sorting, using either the asc or desc values.","enum":["asc","desc"],"example":"desc","type":"string","$$ref":"#/components/schemas/SortOrder"}},"type":"object","$$ref":"#/components/schemas/AgentSearchSort"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/AgentSearchRequest"}}},"description":"The filter options for advanced search filtering for agents.","required":true,"$$ref":"#/components/requestBodies/AgentSearch"},"responses":{"200":{"content":{"application/hal+json":{"schema":{"description":"A list of `EndpointAgents`.","properties":{"totalAgents":{"description":"The total number of agents.","example":1,"type":"integer"},"agents":{"items":{"description":"The `EndpointAgent` object, which may include multiple clients.","properties":{"id":{"description":"Unique ID of endpoint agent, from `/endpoint/agents` endpoint.","example":"861b7557-cd57-4bbb-b648-00bddf88ef49","format":"uuid","readOnly":true,"type":"string"},"aid":{"description":"A unique identifier associated with your account group. You can retrieve your `AccountGroupId` from the `/account-groups` endpoint.","example":"1234","type":"string","$$ref":"#/components/schemas/AccountId","readOnly":true},"name":{"description":"The name of the agent.","example":"Office Printer","readOnly":false,"type":"string"},"computerName":{"example":"DESKJET-123","readOnly":true,"type":"string"},"osVersion":{"example":"Version 10.15.2 (Build 19C57)","readOnly":true,"type":"string"},"platform":{"description":"OS platform types. Platform \"linux\" was recently renamed to \"roomos\".","enum":["windows","roomos","phoneos","elux","linux","mac","unknown"],"example":"mac","type":"string","$$ref":"#/components/schemas/Platform"},"kernelVersion":{"example":"Darwin 19.2.0","readOnly":true,"type":"string"},"manufacturer":{"example":"Apple, Inc.","readOnly":true,"type":"string"},"model":{"example":"MacBookAir7,2","readOnly":true,"type":"string"},"lastSeen":{"description":"The last time the agent checked-in.","example":"2022-05-26T23:37:16Z","format":"date-time","readOnly":true,"type":"string"},"status":{"description":"Status of the endpoint agent in ThousandEyes. Disabled agents don't report data.","enum":["enabled","disabled"],"example":"enabled","readOnly":true,"type":"string","$$ref":"#/components/schemas/Status"},"deleted":{"readOnly":true,"type":"boolean"},"version":{"description":"Version of the agent software running.","example":"0.123.4","readOnly":true,"type":"string"},"createdAt":{"example":"2022-05-26T23:37:16Z","format":"date-time","readOnly":true,"type":"string"},"numberOfClients":{"example":3,"format":"int64","readOnly":true,"type":"integer"},"publicIP":{"example":"88.45.2.123","format":"ip","readOnly":true,"type":"string"},"location":{"description":"Approximate location of the agent.","properties":{"latitude":{"example":51.51279,"format":"double","readOnly":true,"type":"number"},"longitude":{"example":-0.09184,"format":"double","readOnly":true,"type":"number"},"locationName":{"example":"London","readOnly":true,"type":"string"}},"type":"object","$$ref":"#/components/schemas/EndpointAgentLocation"},"clients":{"description":"List of clients (user accounts) that the agent works with.\nNot populated by default.\n","items":{"description":"Information about the user who has the agent installed.","properties":{"userProfile":{"properties":{"userName":{"example":"joeblogs32","type":"string"}},"required":["userName"],"type":"object","$$ref":"#/components/schemas/EndpointUserProfile"},"browserExtensions":{"items":{"properties":{"browser":{"enum":["chrome","chrome-canary","chromium","ie","edge","unknown"],"example":"edge","type":"string","$$ref":"#/components/schemas/BrowserType"},"profile":{"description":"Name of the browser profile where this extension is stored.","example":"Profile 1","type":"string"},"version":{"description":"Endpoint agent browser extension version.","example":"0.123.0","type":"string"},"enabled":{"description":"Indicates if the extension is disabled or enabled in the web browser.","type":"boolean"},"active":{"description":"Flag indicating if there is communication between the extension and ThousandEyes portal.\n","type":"boolean"},"error":{"description":"Contains any errors encountered while getting extension status.","example":"","type":"string"}},"type":"object","$$ref":"#/components/schemas/EndpointBrowserExtension"},"type":"array"}},"type":"object","$$ref":"#/components/schemas/EndpointClient"},"readOnly":true,"type":"array"},"totalMemory":{"example":"16384 MB","readOnly":true,"type":"string"},"agentType":{"example":"endpoint","readOnly":true,"type":"string"},"vpnProfiles":{"description":"List of VPN connections on the agent.\nNot populated by default.\n","items":{"properties":{"interfaceName":{"description":"Interface name associated with `interfaceProfile`.","type":"string"},"vpnType":{"description":"Name of the VPN provider.","enum":["cisco-anyconnect","palo-alto-globalprotect","ivanti-connect-secure","zscaler-internet-access","f5-big-ip"],"example":"cisco-anyconnect","type":"string","$$ref":"#/components/schemas/VpnType"},"vpnGatewayAddress":{"description":"IP address of the VPN gateway.","type":"string"},"vpnClientAddresses":{"description":"List of private IP addresses assigned to the device, by the VPN server.","example":["10.100.0.10"],"items":{"format":"ip","type":"string"},"type":"array"},"vpnClientNetworkRange":{"description":"List of private networks assigned to the device, by the VPN server.","example":["10.100.0.0/22"],"items":{"type":"string"},"type":"array"}},"required":["vpnClientAddresses","vpnClientNetworkRange"],"type":"object","$$ref":"#/components/schemas/EndpointVpnProfile"},"readOnly":true,"type":"array"},"networkInterfaceProfiles":{"description":"List of network interfaces on the agent.\nNot populated by default.\n","items":{"properties":{"interfaceName":{"example":"en0","type":"string"},"addressProfiles":{"items":{"description":"A description of the IPs assigned to this machine.","properties":{"addressType":{"enum":["loopback","unspecified","unique-local","link-local","unique-global"],"example":"unique-local","type":"string","$$ref":"#/components/schemas/AddressType"},"ipAddress":{"description":"IP address of this interface in the network it's currently connected to.","example":"2001:db8:3333:4444:5555:6666:7777:8888","format":"ip","type":"string"},"prefixLength":{"description":"The number of bits representing the network part of the `ipAddress`.","example":24,"format":"int32","type":"integer"},"gateway":{"description":"The default gateway for this interface.","example":"192.168.0.254","format":"ip","type":"string"},"routerHardwareAddress":{"description":"The router's MAC address resolved from an ARP request.","example":"5c:b1:3e:46:1c:84","format":"macaddress","type":"string"}},"type":"object","$$ref":"#/components/schemas/AddressProfile"},"type":"array"},"hardwareType":{"enum":["unknown","wireless","ethernet","modem","virtual","loopback","other"],"example":"wireless","type":"string","$$ref":"#/components/schemas/InterfaceHardwareType"},"ethernetProfile":{"description":"Information about the ethernet connectivity of this device.\nOnly present if the hardware type is `ethernet`.\n","properties":{"linkSpeed":{"description":"Link speed in Mbps.","format":"int32","type":"integer"}},"type":"object","$$ref":"#/components/schemas/EndpointAgentEthernetProfile"},"wirelessProfile":{"properties":{"bssid":{"example":"00:11:22:aa:bb:cc","format":"macaddress","type":"string"},"ssid":{"example":"GuestWiFi","type":"string"},"rssi":{"example":-36,"format":"int32","type":"integer"},"channel":{"example":48,"format":"int32","type":"integer"},"phyMode":{"example":"802.11ac","type":"string"}},"type":"object","$$ref":"#/components/schemas/WirelessProfile"}},"type":"object","$$ref":"#/components/schemas/InterfaceProfile"},"readOnly":true,"type":"array"},"asnDetails":{"properties":{"asNumber":{"description":"Autonomous system number.","example":5089,"format":"int64","type":"integer"},"asName":{"description":"Name of autonomous system.","example":"Virgin Media Limited","type":"string"}},"readOnly":true,"required":["asNumber"],"type":"object","$$ref":"#/components/schemas/EndpointAsnDetails"},"licenseType":{"enum":["essentials","advantage","embedded"],"example":"essentials","type":"string","$$ref":"#/components/schemas/AgentLicenseType"},"tcpDriverAvailable":{"description":"Status of TCP test support on the agent.","readOnly":true,"type":"boolean"},"npcapVersion":{"description":"For Windows agents, the version of the NPCAP driver that the agent has loaded.","readOnly":true,"type":"string"},"_links":{"description":"A links object containing the self link.","properties":{"self":{"description":"A hyperlink from the containing resource to a URI.","properties":{"href":{"description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id","type":"string"},"templated":{"description":"Should be true when the link object's \"href\" property is a URI template.","type":"boolean"},"type":{"description":"Used as a hint to indicate the media type expected when dereferencing the target resource.","type":"string"},"deprecation":{"description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.","type":"string"},"name":{"description":"Its value may be used as a secondary key for selecting link objects that share the same relation type.","type":"string"},"profile":{"description":"A URI that hints about the profile of the target resource.","type":"string"},"title":{"description":"Intended for labelling the link with a human-readable identifier","type":"string"},"hreflang":{"description":"Indicates the language of the target resource","type":"string"}},"required":["href"],"type":"object","$$ref":"#/components/schemas/Link"}},"readOnly":true,"type":"object","$$ref":"#/components/schemas/SelfLinks"}},"type":"object","$$ref":"#/components/schemas/EndpointAgent"},"type":"array","x-paginated-items":true},"_links":{"description":"A links object containing a related link for forward pagination.","properties":{"next":{"description":"A hyperlink from the containing resource to a URI.","properties":{"href":{"description":"Its value is either a URI [RFC3986] or a URI template [RFC6570].","example":"https://api.thousandeyes.com/v7/link/to/resource/id","type":"string"},"templated":{"description":"Should be true when the link object's \"href\" property is a URI template.","type":"boolean"},"type":{"description":"Used as a hint to indicate the media type expected when dereferencing the target resource.","type":"string"},"deprecation":{"description":"Its presence indicates that the link is to be deprecated at a future date. Its value is a URL that should provide further information about the deprecation.","type":"string"},"name":{"description":"Its value may be used as a secondary key for selecting link objects that share the same relation type.","type":"string"},"profile":{"description":"A URI that hints about the profile of the target resource.","type":"string"},"title":{"description":"Intended for labelling the link with a human-readable identifier","type":"string"},"hreflang":{"description":"Indicates the language of the target resource","type":"string"}},"required":["href"],"type":"object","$$ref":"#/components/schemas/Link"}},"type":"object","$$ref":"#/components/schemas/PaginationNextLink"}},"type":"object","$$ref":"#/components/schemas/FilterEndpointAgentsResponse"}}},"description":"OK"},"400":{"content":{"application/problem+json":{"example":{"type":"about:blank","title":"Request validation failed. There are invalid or missing fields","status":400,"detail":"Your request object contains invalid fields.","instance":"/v7","errors":[{"code":"AM-5432","field":"firstName","message":"firstName cannot have fancy characters"},{"code":"DASH-5622","field":"password","message":"Password cannot be blank"}]},"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"},"errors":{"description":"(Optional) When multiple errors occur, the details for each error are listed.","items":{"properties":{"code":{"description":"(Optional) A unique error type/code that can be referenced in the documentation for further details.","type":"string"},"field":{"description":"Identifies the field that triggered this particular error.","type":"string"},"message":{"description":"A short, human-readable summary of the error.","type":"string"}},"type":"object","$$ref":"#/components/schemas/ValidationErrorItem"},"nullable":true,"type":"array"}},"type":"object","$$ref":"#/components/schemas/ValidationError"}}},"description":"Bad Request"},"401":{"content":{"application/problem+json":{"schema":{"properties":{"error":{"example":"invalid_token","type":"string"},"error_description":{"example":"Invalid access token","type":"string"}},"type":"object","$$ref":"#/components/schemas/UnauthorizedError"}}},"description":"Unauthorized"},"403":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Insufficient permissions to query endpoint"},"429":{"content":{"application/problem+json":{"schema":{"properties":{"type":{"description":"A URI reference that identifies the problem type. When this member is not present, its value is assumed to be \"about:blank\".","type":"string"},"title":{"description":"A short, human-readable summary of the problem type.","type":"string"},"status":{"description":"The HTTP status code generated by the origin server for this occurrence of the problem.","type":"integer"},"detail":{"description":"A human-readable explanation specific to this occurrence of the problem.","type":"string"},"instance":{"description":"A URI reference that identifies the specific occurrence of the problem.","type":"string"}},"type":"object","$$ref":"#/components/schemas/Error"}}},"description":"Exhausted rate limit for the organization"}},"summary":"Filter endpoint agents","tags":["Endpoint Agents"],"__originalOperationId":"filterEndpointAgents","security":[{"BearerAuth":[]}],"method":"post","path":"/endpoint/agents/filter"}}