Cato Networks Knowledge Base

Cato API - AccountSnapshot > Users

  • Updated

AccountSnapshot > Users

The UserSnapshot field contains data related to VPN users in the account. When you run a query for all users in the account (the ID argument is empty), then the API call returns data for users that are currently connected to the VPN and the Cato Cloud.

If you use the ID argument to run a query for specific users, the API call returns data for those users even when they aren't connected to the VPN.

UserSnapshot Fields

The UserSnapshot fields contain data for connected VPN users and their connections to the Cato Cloud. Use the IDs argument to specify which VPN users are included in the query.

These are the details that the UserSnapshot fields can return for the query:

  • id - VPN user ID
  • connectivityStatus - connectivity to the Cato Cloud (array with nested fields)
  • operationalStatus - status for a site or VPN user (array with nested fields)
  • name - name of the VPN user
  • deviceName - name of the computer or device
  • uptime - how long the Client has been connected to the Cato Cloud (in seconds)
  • lastConnected - timestamp for when the VPN user connected to the PoP
  • version - Client software version (string)
  • versionNumber - Client software version (INT)
  • popID - ID of the PoP that the Client is connected to
  • popName - name of the PoP that the VPN user is connected to
  • RemoteIP - IP address of the Client
  • RemoteIPInfo - IP address, ISP, and geographical information related to the Client
  • internalIP - IP address of the PoP that the Client is connected to
  • osType - operating system of the device the Client is running on
  • osVersion - version of the operating system for the device
  • devices - data related to the Client (array with nested fields)
  • connectedInOffice - shows if the Client is connected to the VPN using Office Mode
  • metrics - real-time (based on the last 30 seconds) traffic metrics and data for the Client (array with nested fields)
  • info - general information about the VPN user (array with nested fields)
  • recentConnections - data related to the most recent completed VPN connections (array with nested queries and fields)

ID

Shows the unique VPN user internal ID for the account, this value isn't shown in the Cato Management Application.

connectivityStatus

The Users > connectivityStatus field shows the connectivity for a VPN user:

  • connected to the Cato Cloud
  • disconnected from the Cato Cloud

operationalStatus

The Users > operationalStatus field shows the VPN user status:

  • active - passing traffic
  • disabled - disabled in the Cato Management Application
  • locked - account for this VPN user is locked
  • new - not relevant for VPN users
  • pending_user_configuration - waiting for the VPN user to confirm the account
  • pending_mfa_configuration - waiting for the VPN user to configure the MFA settings
  • pending_code_generation - waiting for the VPN user to enter the registration code

Name

The name field shows the name of the VPN user in the Cato Management Application.

DeviceName

The deviceName field shows the name of the computer or device that is connected to the Cato Cloud.

uptime

The uptime field shows the total amount of time in seconds, that the VPN user is connected to the Cato Cloud.

lastConnected

For a VPN user that isn't connected to the Cato Cloud, the lastConnected field shows the time stamp for the last time the Client connected to the Cato Cloud.

version

The version field shows the version of the Client as the type STRING.

versionNumber

The versionNumber field shows the version of the Client as the type INT.

PopID

The Users > PoPID field shows the ID of the PoP that the Client is connected to.

PopName

The Users > PoPName field shows the name of the PoP that the Client is connected to.

RemoteIP

The Users > RemoteIP field shows the IP address of the Client.

RemoteIPInfo

The Users > RemoteIPInfo fields shows data related to the IP address, ISP, and physical location of the PoP that the Client is connected to. These are the details for the fields:

  • ip - IP address of the WAN connection to the PoP
  • countryCode - code for the physical location of the PoP (based on IP address geo-location)
  • countryName - country that is the physical location of the PoP (based on IP address geo-location)
  • city - city where the PoP is located (based on IP address geo-location)
  • state - state where the PoP is located (based on IP address geo-location)
  • provider - ISP provider for the last-mile connection between the Cato Cloud and the PoP
  • latitude - latitude of the PoP (based on IP address geo-location)
  • longitude - longitude of the PoP (based on IP address geo-location)

InternalIP

The Users > internalIP field shows the IP address of the PoP that the Client is connected to.

osType

The osType field shows the operating system of the device that the Client is installed on.

osVersion

The osVersion field shows the operating system version of the device that the Client is installed on.

Devices

The Users > DeviceSnapshot fields show metrics and data of the device that is connected to the Cato Cloud. Some fields in DeviceSnapshot are repeated to give you greater flexibility with the data. Also, the same DeviceSnapshot infrastructure is used for VPN users and for sites, and some of the fields are only relevant to users or sites.

This is the data that you can see:

  • id - unique internal Cato ID for the device
  • name - name of the device
  • identifier - unique identifier for the device
  • connected - a boolean value that indicates if the Client is connected to the Cato Cloud
  • haRole - this field is used in SiteSnapshot > Site> Devices
  • interfaces - shows real-time data for the Client (array with nested queries and fields)

    For more about the Interfaces fields for DeviceSnapshot, see Cato API - AccountSnapshot > Sites > Devices > Interfaces.

  • lastConnected - timestamp for when the Client connected to the Cato Cloud
  • lastDuration - total amount of time that the Client has been connected to the Cato Cloud
  • connectedSince - shows the timestamp for how long the Client is actively connected to the Cato Cloud
  • lastPopName - the PoP name that the Client is connected to
  • lastPopID - the ID of the PoP that the Client is connected to
  • metrics - real-time traffic metrics and data for the Socket (array with nested queries and fields)

    For more about the Metrics fields for DeviceSnapshot, see Cato API - AccountSnapshot > Sites > Devices > Interfaces.

  • recentConnections - data related to the most recent completed traffic flows (array with nested queries and fields)

    For more about the recentConnections fields for DeviceSnapshot, see Cato API - AccountSnapshot > Sites > Devices.

  • type - shows the device type
  • uptimeSeconds - shows the number of seconds that this Client has been active
  • socketInfo - this field is used in SiteSnapshot > Site> Devices
  • interfacesLinkState - this field is used in SiteSnapshot > Site> Devices
  • osType - operating system of the device the Client is running on
  • osVersion - version of the operating system for the device
  • version - Client software version, for example 4.4.1234 (string)
  • versionNumber - Client major software version, for example 4 (INT)
  • releaseGroup - shows the release status for the Client, such as GA or EA
  • mfaExpirationTime - Shows the amount of time remaining before the MFA token expires

connectedInOffice

The connectedInOffice field is a boolean value, and when it is true, it shows that the Client is connected to the network using Office Mode.

Metrics

The Users > Metrics fields show the real-time traffic analytics for the Client. This the data that you can see:

  • duration - total amount of time for the Client data
  • granularity - duration in seconds for a single metrics bucket
  • bytesDownstream - total downstream traffic (from the Cato Cloud to the Client)
  • bytesUpstream - total upstream traffic (from the Client to the Cato Cloud)
  • bytesTotal - total traffic for the Client
  • lostDownstream - number of packets lost for downstream traffic
  • lostDownstreamPcnt - percent of packets lost for downstream traffic
  • lostUpstream - number of packets lost for upstream traffic
  • lostUpstreamPcnt - percent of packets lost for upstream traffic
  • packetsDownstream - total downstream packets
  • packetsUpstream - total upstream packets
  • jitterUptstream - jitter for upstream traffic (difference in time delay in milliseconds (ms) between data packets)
  • jitterDownstream - jitter for downstream traffic (difference in time delay in milliseconds (ms) between data packets)
  • packetsDiscardedDownstream - total packets discarded for downstream traffic
  • packetsDiscardedUpstream - total packets discarded for upstream traffic
  • rtt - round-trip time from the Client to the Cato Cloud

Info

The UserInfo fields show basic information about the VPN user, in a concise branch. These are the details for the fields:

  • name - name of the VPN user
  • status - status of the Client as the type STRING
  • email - email address of the VPN user
  • creationTime - timestamp when the VPN user was created in the account
  • phoneNumber - phone number for the VPN user
  • origin - shows how the VPN user was added to the account:
    • regular - manually added in the Cato Management Application
    • LDAP - added with LDAP sync
  • authMethod - Multi Factor Authentication (MFA) settings for this VPN user:
    • None - the VPN user doesn't require MFA to authenticate to the Client
    • MFA - the VPN user requires MFA to authenticate to the Client

RecentConnections

The Users > RecentConnections field shows data related to the most recent Client connections to the Cato Cloud. These are the details that this field can return for a query:

  • duration - total amount of time for the query data
  • interfaceName - Name for the port in the Cato Management Application
  • deviceName - Name of the device the Client is installed on
  • lastConnected - Shows the time stamp when the Client initiated the connection to the Cato Cloud
  • popID - The ID of the PoP that the Client was connected to
  • popName - The name of the PoP that the Client was connected to
  • remoteIP - IP address of the Client
  • remoteIPInfo - IP address, ISP, and geographical information related to the PoP that the traffic flow was connected to

Snapshot > Users IDs Argument

Enter the VPN user IDs for the data that the query returns. When this argument is empty, the query returns all the VPN users for connected to the Cato Cloud.

Was this article helpful?

0 out of 0 found this helpful

Comments

0 comments

Please sign in to leave a comment.