Cato Networks GraphQL API Reference

Reference documentation for Cato GraphQL API

Contact

Cato Networks Support

api@catonetworks.com

API Endpoints
https://api.catonetworks.com/api/v1/graphql2

Further readings

GraphQL Introspection Query

Use the GraphQL Introspection system to learn more about queries and types with the Cato API schema.

For more information, see the GraphQL Documentation.

Queries

accountBySubdomain

Response

Returns [AccountDataPayload!]

Arguments
Name Description
accountID - ID!
subdomains - [String!]! a list of required subdomains

Example

Query
query accountBySubdomain($accountID:ID!, $subdomains:[String!]!) {
  accountBySubdomain(accountID:$accountID, subdomains:$subdomains) {
    id
    subdomain
  }
}
Variables
{"accountID": "123", "subdomains": ["company"]}
Response
{"data": {"accountBySubdomain": [{"id": "123", "subdomain": "company"}]}}

accountMetrics

Description

The accountMetrics query helps you analyze the state and quality of the connections of sites and SDP users to the Cato Cloud. This data is for the traffic inside the DTLS tunnel between the site and the Cato Cloud. accountMetrics shows historical metrics, statics, and analytics for the account.

Response

Returns an AccountMetrics

Arguments
Name Description
accountID - ID Unique Identifier of Account.
timeFrame - TimeFrame! The time frame for the data that the query returns. The argument is in the format type.time value. This argument is mandatory.
groupInterfaces - Boolean When the boolean argument groupInterfaces is set to true, then the data for all the interfaces are aggregated to a single interface.
groupDevices - Boolean

When the boolean argument groupDevices is set to true, then the analytics for all the Sockets (usually two in high availability) are aggregated as one result.

For the best results for aggregated Sockets, we recommend that there is consistent names and functionality (for example Destination) for the links on both Sockets.

Note: This argument is mandatory for queries of multiple sites and the only valid value for groupDevices value is true.

Example

Query
query accountMetrics(
  $accountID:ID!,
  $timeFrame:TimeFrame!,
  $groupInterfaces: Boolean,
  $groupDevices: Boolean,
  $siteIDs: [ID!]
) {
  accountMetrics(
    accountID:$accountID,
    timeFrame: $timeFrame,
    groupInterfaces: $groupInterfaces,
    groupDevices: $groupDevices
  ) {
    id
    from
    to
    sites(siteIDs:$siteIDs) {
      id
      metrics {
        bytesUpstream
        bytesDownstream
      }
      interfaces {
        name
        metrics {
          bytesUpstream
          bytesDownstream
        }
      }
    }
  }
}
Variables
{
  "accountID": "123",
  "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}",
  "groupInterfaces": false,
  "groupDevices": true,
  "siteIDs": ["456", "789"]
}
Response
{
  "data": {
    "accountMetrics": {
      "id": "123",
      "from": "2023-02-28T00:00:00Z",
      "to": "2023-02-28T23:59:59Z",
      "sites": [
        {
          "id": "456",
          "metrics": {"bytesUpstream": 122324400, "bytesDownstream": 8354720},
          "interfaces": [
            {
              "name": "WAN 01",
              "metrics": {
                "bytesUpstream": 122324400,
                "bytesDownstream": 8354720
              }
            }
          ]
        },
        {
          "id": "789",
          "metrics": {"bytesUpstream": 100254955, "bytesDownstream": 3907080},
          "interfaces": [
            {
              "name": "WAN 01",
              "metrics": {
                "bytesUpstream": 100254955,
                "bytesDownstream": 3907080
              }
            }
          ]
        }
      ]
    }
  }
}

accountRoles

Response

Returns an AccountRolesResult!

Arguments
Name Description
accountID - ID!
accountType - AccountType

Example

Query
query accountRoles($accountID:ID!){
  accountRoles(accountID: $accountID) {
    items {
      name
      isPredefined
    }
    total
  }
}
Variables
{"accountID": "123"}
Response
{
  "data": {
    "accountRoles": {
      "items": [
        {"name": "Editor", "isPredefined": true},
        {"name": "Viewer", "isPredefined": true},
        {"name": "Network admin", "isPredefined": true},
        {"name": "Security Admin", "isPredefined": true},
        {"name": "Access Admin", "isPredefined": true}
      ],
      "total": 5
    }
  }
}

accountSnapshot

Description

Current snapshot-based metrics that show near real‑time data for the account. Provides analytics that are similar to the Topology page for the account.

Response

Returns an AccountSnapshot

Arguments
Name Description
accountID - ID Unique Identifier of Account.

Example

Query
query accountSnapshot($accountID:ID!) {
  accountSnapshot(accountID:$accountID) {
    sites {
      connectivityStatus
      haStatus{
        readiness
        wanConnectivity
        keepalive
        socketVersion
      }
      operationalStatus
      lastConnected
      connectedSince
      devices {
        connected
        version
      }
    }
    users {
      connectivityStatus
      connectedInOffice
      name
      deviceName
    }
    timestamp
  }
}
Variables
{"accountID": "123"}
Response
{
  "data": {
    "accountSnapshot": {
      "sites": [
        {
          "connectivityStatus": "connected",
          "haStatus": {
            "readiness": "ready",
            "wanConnectivity": "ok",
            "keepalive": "ok",
            "socketVersion": "ok"
          },
          "operationalStatus": "active",
          "lastConnected": "2023-02-28T13:21:05Z",
          "connectedSince": "2023-02-27T15:10:06Z",
          "devices": [
            {"connected": true, "version": "17.0.16303"},
            {"connected": true, "version": "17.0.16303"}
          ]
        },
        {
          "connectivityStatus": "disconnected",
          "haStatus": null,
          "operationalStatus": "active",
          "lastConnected": "2020-03-11T13:43:40Z",
          "connectedSince": null,
          "devices": [{"connected": false, "version": ""}]
        }
      ],
      "users": [
        {
          "connectivityStatus": "connected",
          "connectedInOffice": false,
          "name": "Employee Domywork",
          "deviceName": "Employee’s MacBook Pro"
        },
        {
          "connectivityStatus": "connected",
          "connectedInOffice": false,
          "name": "Alice Bobs",
          "deviceName": "Alice’s MacBook Pro"
        }
      ],
      "timestamp": "2023-02-28T13:22:21Z"
    }
  }
}

admin

Response

Returns a GetAdminPayload

Arguments
Name Description
accountId - ID!
adminID - ID!

Example

Query
query admin($accountId:ID!, $adminID:ID!) {
  admin(accountId:$accountId, adminID:$adminID) {
    id
    firstName
    lastName
    email
    creationDate
    mfaEnabled
    managedRoles {
      role {
        name
      }
    }
  }
}
Variables
{"accountId": "123", "adminID": "456"}
Response
{
  "data": {
    "admin": {
      "id": "456",
      "firstName": "Name",
      "lastName": "Surname",
      "email": "name.surname@company.org",
      "creationDate": "Dec 27, 2020 9:30:34 AM",
      "mfaEnabled": false,
      "managedRoles": [{"role": {"name": "Viewer"}}]
    }
  }
}

admins

Response

Returns an AdminsResult

Arguments
Name Description
accountID - ID!
limit - Int Default = 50
from - Int Default = 0
search - String Default = ""
sort - [SortInput]
adminIDs - [ID!]

Example

Query
query admins($accountId:ID!, $limit: Int) {
  admins(accountID:$accountId, limit: $limit) {
    items {
      id
      email
      managedRoles {
        role {
          name
        }
      }
    }
    total
  }
}
Variables
{"accountId": "123", "limit": 2}
Response
{
  "data": {
    "admins": {
      "items": [
        {
          "id": "1",
          "email": "editor@company.org",
          "managedRoles": [{"role": {"name": "Editor"}}]
        },
        {
          "id": "2",
          "email": "viewer@company.org",
          "managedRoles": [{"role": {"name": "Viewer"}}]
        }
      ],
      "total": 3
    }
  }
}

appStats

Description

BETA

Response

Returns an AppStats

Arguments
Name Description
accountID - ID! Account ID
timeFrame - TimeFrame!
measures - [Measure]
dimensions - [Dimension]
filters - [AppStatsFilter!]
sort - [AppStatsSort!]

Example

Query
query appStats(
  $accountID:ID!, 
  $timeFrame:TimeFrame!,
  $measures: [Measure],
  $dimensions:[Dimension],
  $sort:[AppStatsSort!],
  $limit:Int,
  $from:Int,
) {
  appStats(
    accountID: $accountID,
    timeFrame: $timeFrame,
    measures: $measures,
    dimensions:$dimensions,
    sort:$sort,
  ) {
    from
    to
    records(limit:$limit, from:$from){
      fieldsMap
      fieldsUnitTypes
    }
  }
}
Variables
{
  "accountID": "123",
  "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}",
  "dimensions": [{"fieldName": "app"}],
  "sort": [{"fieldName": "traffic", "order": "desc"}],
  "measures": [
    {"fieldName": "traffic", "aggType": "sum"},
    {"fieldName": "application", "aggType": "any"}
  ],
  "limit": 5,
  "from": 0
}
Response
{
  "data": {
    "appStats": {
      "from": "2023-02-28T00:00:00Z",
      "to": "2023-03-01T00:00:00Z",
      "records": [
        {
          "fieldsMap": {
            "app": "zoom",
            "application": "Zoom",
            "traffic": "95138282696"
          },
          "fieldsUnitTypes": ["none", "none", "bytes"]
        },
        {
          "fieldsMap": {
            "app": "udp",
            "application": "UDP",
            "traffic": "45401221439"
          },
          "fieldsUnitTypes": ["none", "none", "bytes"]
        },
        {
          "fieldsMap": {
            "app": "Tech",
            "application": "Technological apps",
            "traffic": "13982474567"
          },
          "fieldsUnitTypes": ["none", "none", "bytes"]
        },
        {
          "fieldsMap": {
            "app": "AppleSoftwareupdate",
            "application": "Apple software update",
            "traffic": "11624258191"
          },
          "fieldsUnitTypes": ["none", "none", "bytes"]
        }
      ]
    }
  }
}

appStatsTimeSeries

Description

BETA

Response

Returns an AppStatsTimeSeries

Arguments
Name Description
accountID - ID! Account ID
timeFrame - TimeFrame!
measures - [Measure]
dimensions - [Dimension]
filters - [AppStatsFilter!]

Example

Query
query appStatsTimeSeries(
  $accountID:ID!,
  $timeFrame:TimeFrame!,
  $measures: [Measure],
  $buckets:Int!
) {
  appStatsTimeSeries(
    accountID:$accountID,
    timeFrame:$timeFrame,
    measures: $measures
  ) {
    from
    to
    granularity
    timeseries(buckets:$buckets) {
      label
      data
      key {
        measureFieldName
      }
    }
  }
}
Variables
{
  "accountID": "123",
  "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}",
  "measures": [
    {"fieldName": "upstream", "aggType": "sum"},
    {"fieldName": "downstream", "aggType": "sum"}
  ],
  "buckets": 5
}
Response
{
  "data": {
    "appStatsTimeSeries": {
      "from": "2023-02-28T00:00:00Z",
      "to": "2023-03-01T00:00:00Z",
      "granularity": 14400,
      "timeseries": [
        {
          "label": "sum(upstream)",
          "data": [
            [1677542400000, 77192],
            [1677556800000, 742410],
            [1677571200000, 5335372],
            [1677585600000, 2239509],
            [1677600000000, 0],
            [1677614400000, 0]
          ],
          "key": {"measureFieldName": "upstream"}
        },
        {
          "label": "sum(downstream)",
          "data": [
            [1677542400000, 209763],
            [1677556800000, 1713925],
            [1677571200000, 7719290],
            [1677585600000, 2573650],
            [1677600000000, 0],
            [1677614400000, 0]
          ],
          "key": {"measureFieldName": "downstream"}
        }
      ]
    }
  }
}

auditFeed

Description

Audit Feed for account changes

Response

Returns an AuditFeed

Arguments
Name Description
accountIDs - [ID!] List of Unique Account Identifiers.
timeFrame - TimeFrame!
filters - [AuditFieldFilterInput!]
marker - String Marker to use to get results from

Example

Query
query auditFeed($accountID:ID!, $timeFrame: TimeFrame!){
  auditFeed(accountIDs:[$accountID], timeFrame:$timeFrame) {
    from
    to
    fetchedCount
    accounts {
      id
      records{
        admin {
          name
        }
        object {
          name
        }
        time
        fields {
          name
          value {
            ... on Entity {
              name
              id
              type
            }
            ... on StringValue {
              string
            }
            ... on DateValue {
              date
            }
          }
        }
      }
    }
  }
}
Variables
{"accountID": "123", "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}"}
Response
{
  "data": {
    "auditFeed": {
      "from": "2023-02-28T00:00:00Z",
      "to": "2023-02-28T23:59:59Z",
      "fetchedCount": 1,
      "accounts": [
        {
          "id": "123",
          "records": [
            {
              "time": "2023-02-28T08:48:21Z",
              "fields": [
                {
                  "name": "admin",
                  "value": {
                    "name": "admin@company.org",
                    "id": "456",
                    "type": "admin"
                  }
                },
                {
                  "name": "change.Before.description",
                  "value": {"string": "Description before change"}
                },
                {
                  "name": "change.After.description",
                  "value": {"string": "Description after change"}
                },
                {"name": "model_name", "value": {"string": "Site name"}},
                {"name": "module", "value": {"string": "Configuration"}},
                {"name": "change_type", "value": {"string": "MODIFIED"}},
                {"name": "creation_date", "value": {"string": "1677574090000"}},
                {"name": "model_type", "value": {"string": "Site"}},
                {"name": "admin_id", "value": {"string": "456"}},
                {
                  "name": "insertion_date",
                  "value": {"date": "2023-02-28T08:48:21Z"}
                },
                {"name": "account_id", "value": {"string": "123"}}
              ]
            }
          ]
        }
      ]
    }
  }
}

entityLookup

Description

Lookup entities with a specific type, potentially filtered and paged

Response

Returns an EntityLookupResult!

Arguments
Name Description
accountID - ID! The account ID (or 0 for non-authenticated requests)
type - EntityType! Type of entity to lookup for
limit - Int Sets the maximum number of items to retrieve. Default = 50
from - Int Sets the offset number of items (for paging). Default = 0
parent - EntityInput Return items under a parent entity (can be site, vpn user, etc), used to filter for networks that belong to a specific site for example
search - String Adds additional search parameters for the lookup. Available options: country lookup: "removeExcluded" to return only allowed countries countryState lookup: country code ("US", "CN", etc) to get country's states. Default = ""
entityIDs - [ID!] Adds additional search criteria to fetch by the selected list of entity IDs. This option is not universally available, and may not be applicable specific Entity types. If used on non applicable entity type, an error will be generated.
sort - [SortInput] Adds additional sort criteria(s) for the lookup. This option is not universally available, and may not be applicable specific Entity types.
filters - [LookupFilterInput] Custom filters for entityLookup
helperFields - [String!] Additional helper fields

Example

Query
query entityLookup($accountID:ID!, $limit:Int, $type:EntityType!) {
  entityLookup(accountID: $accountID, type:$type, limit: $limit) {
    items {
      entity{
        id
        name
      }
    }
    total
  }
}
Variables
{"accountID": "123", "limit": 2, "type": "site"}
Response
{
  "data": {
    "entityLookup": {
      "items": [
        {"entity": {"id": "45040", "name": "azure_test"}},
        {"entity": {"id": "75791", "name": "esx_test"}}
      ],
      "total": 5
    }
  }
}

events

Description

BETA

Response

Returns an Events

Arguments
Name Description
accountID - ID! Account ID
timeFrame - TimeFrame!
measures - [EventsMeasure]
dimensions - [EventsDimension]
filters - [EventsFilter!]
sort - [EventsSort!]

Example

Query
query events($accountID:ID!, $timeFrame:TimeFrame!, ) {
  events(accountID: $accountID, timeFrame:$timeFrame, measures: {fieldName: event_count, aggType: sum}) {
    records {
      flatFields
      fieldsMap
    }
  }
}
Variables
{"accountID": "123", "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}"}
Response
{
  "data": {
    "events": {
      "records": [
        {
          "flatFields": [["event_count", "2"]],
          "fieldsMap": {"event_count": "2"}
        }
      ]
    }
  }
}

eventsFeed

Description

Event Feed for events paged by a topic partitions offsets marker

Response

Returns an EventsFeedData

Arguments
Name Description
accountIDs - [ID!] List of Unique Account Identifiers.
filters - [EventFeedFieldFilterInput!]
marker - String Marker to use to get results from

Example

Query
query eventsFeed(
  $accountIDs: [ID!],
  $filters: [EventFeedFieldFilterInput!]
) {
  eventsFeed(
    accountIDs: $accountIDs,
    filters: $filters,
  ) {
    marker
    fetchedCount
    accounts {
      id
      errorString
      records {
        fieldsMap
      }
    }
  }
}
Variables
{
  "accountIDs": [123],
  "filters": [
    {
      "fieldName": "event_type",
      "operator": "is_not",
      "values": ["Sockets Management"]
    },
    {
      "fieldName": "event_sub_type",
      "operator": "is",
      "values": ["Disconnected"]
    }
  ]
}
Response
{
  "data": {
    "eventsFeed": {
      "marker": "W3siVG9waWMiOiIxODIiLCJQYXJ0aXRpb24iOjAsIk9mZnNldCI6MzIxNTM4fV0=",
      "fetchedCount": 1,
      "accounts": [
        {
          "id": "123",
          "errorString": "",
          "records": [
            {
              "fieldsMap": {
                "ISP_name": "IP Addresses Are Assigned Statically",
                "account_id": "123",
                "client_version": "8.0.4127",
                "event_count": "1",
                "event_sub_type": "Disconnected",
                "event_type": "Connectivity",
                "internalId": "7r0c7xUYIf",
                "link_type": "Cato",
                "pop_name": "Amsterdam",
                "socket_interface": "WAN1",
                "src_country": "Israel",
                "src_country_code": "IL",
                "src_is_site_or_vpn": "Site",
                "src_isp_ip": "1.2.3.4",
                "src_site": "native-range",
                "time": "1677170467000",
                "tunnel_protocol": "DTLS"
              }
            }
          ]
        }
      ]
    }
  }
}

eventsTimeSeries

Description

BETA

Response

Returns an EventsTimeSeries

Arguments
Name Description
accountID - ID! Account ID
timeFrame - TimeFrame!
measures - [EventsMeasure]
dimensions - [EventsDimension]
filters - [EventsFilter!]

Example

Query
query eventsTimeSeries(
  $accountID: ID!,
  $filters: [EventsFilter!],
  $timeFrame: TimeFrame!,
  $measures: [EventsMeasure],
  $buckets: Int!
) {
  eventsTimeSeries(
    accountID: $accountID,
    filters: $filters,
    timeFrame:$timeFrame,
    measures: $measures
  ) {
    id
    from
    to
    granularity
    timeseries(buckets:$buckets) {
      label
      data
    }
  }
}
Variables
{
  "accountID": "4125",
  "timeFrame": "utc.2023-02-{28/00:00:00--28/23:59:59}",
  "measures": [{"fieldName": "event_count", "aggType": "sum"}],
  "buckets": 4
}
Response
{
  "data": {
    "eventsTimeSeries": {
      "id": "4125",
      "from": "2023-02-28T00:00:00Z",
      "to": "2023-03-01T00:00:00Z",
      "granularity": 21600,
      "timeseries": [
        {
          "label": "sum(event_count)",
          "data": [
            [1677542400000, 5],
            [1677564000000, 2],
            [1677585600000, 0],
            [1677607200000, 5]
          ]
        }
      ]
    }
  }
}

subDomains

Description

The subdomain query helps you retrieve the URL of an account. The usage of this query supports 3 different scenarios:

  1. Regular account - Return only 1 subdomain relating to the regular account
  2. Reseller account - Return all subdomains including the reseller account subdomain
  3. Reseller account - Return only the reseller account subdomain
Response

Returns [SubDomain!]!

Arguments
Name Description
accountID - ID! Unique Identifier of Account
managedAccount - Boolean When the boolean argument managedAccount is set to true (default), then the query returns all subdomains related to the account

Example

Query
query subDomains($accountID:ID!, $managedAccount:Boolean) {
  subDomains(accountID:$accountID, managedAccount:$managedAccount) {
      accountId
      accountName
      accountType
      subDomain
  }
}
Variables
{"accountID": "123", "managedAccount": true}
Response
{
  "data": {
    "subDomains": [
      {
        "accountId": "123",
        "accountName": "Gamma LLC",
        "accountType": "Reseller",
        "subdomain": "subdomain3"
      },
      {
        "accountId": "1235",
        "accountName": "Delta Inc.",
        "accountType": "Regular",
        "subdomain": "subdomain4"
      }
    ]
  }
}

Mutations

AdminMutations

addAdmin

Response

Returns an AddAdminPayload

Arguments
Name Description
input - AddAdminInput!

Example

Query
mutation addAdmin($accountId:ID!, $input: AddAdminInput!) {
  admin(accountId:$accountId) {
    addAdmin(input:$input) {
      adminID
    }
  }
}
Variables
{
  "accountId": "123",
  "input": {
    "firstName": "Name",
    "lastName": "Surname",
    "email": "name.surname@company.org",
    "passwordNeverExpires": false,
    "mfaEnabled": true,
    "managedRoles": [{"role": {"id": 2, "name": "Viewer"}}]
  }
}
Response
{"data": {"admin": {"addAdmin": {"adminID": "456"}}}}

removeAdmin

Response

Returns a RemoveAdminPayload

Arguments
Name Description
adminID - ID!

Example

Query
mutation removeAdmin($accountId:ID!, $adminID:ID!){
  admin(accountId:$accountId) {
    removeAdmin(adminID:$adminID) {
      adminID
    }
  }
}
Variables
{"accountId": "123", "adminID": "456"}
Response
{"data": {"admin": {"removeAdmin": {"adminID": "456"}}}}

updateAdmin

Response

Returns an UpdateAdminPayload

Arguments
Name Description
adminID - ID!
input - UpdateAdminInput!

Example

Query
mutation updateAdmin($accountId:ID!, $adminID:ID!, $input: UpdateAdminInput!){
  admin(accountId:$accountId) {
    updateAdmin(adminID:$adminID,input:$input) {
      adminID
    }
  }
}
Variables
{
  "accountId": "123",
  "adminID": "456",
  "input": {
    "managedRoles": [
      {"role": {"id": 1, "name": "Editor"}},
      {"role": {"id": 2, "name": "Viewer"}}
    ]
  }
}
Response
{"data": {"admin": {"updateAdmin": {"adminID": "456"}}}}

SiteMutations

addSocketSite

Response

Returns an AddSocketSitePayload

Arguments
Name Description
input - AddSocketSiteInput!

Example

Query
mutation addSocketSite($accountId:ID!, $input:AddSocketSiteInput!){
  site(accountId:$accountId) {
    addSocketSite(input:$input) {
      siteId
    }
  }
}
Variables
{
  "accountId": 123,
  "input": {
    "name": "New Site",
    "connectionType": "SOCKET_X1700",
    "siteType": "DATACENTER",
    "description": "Data warehouse",
    "nativeNetworkRange": "123.0.0.0/24",
    "siteLocation": {"countryCode": "IL", "timezone": "Asia/Jerusalem"}
  }
}
Response
{"data": {"site": {"addSocketSite": {"siteId": "456"}}}}

updateSiteGeneralDetails

Response

Returns an UpdateSiteGeneralDetailsPayload

Arguments
Name Description
siteId - ID!
input - UpdateSiteGeneralDetailsInput!

Example

Query
mutation updateSiteGeneralDetails($accountId:ID!, $siteId:ID!, $input:UpdateSiteGeneralDetailsInput!) {
  site(accountId: $accountId){
    updateSiteGeneralDetails(siteId:$siteId, input:$input) {
      siteId
    }
  }
}
Variables
{"accountId": "123", "siteId": "456", "input": {"siteType": "BRANCH"}}
Response
{"data": {"site": {"updateSiteGeneralDetails": {"siteId": "456"}}}}

removeSite

Response

Returns a RemoveSitePayload

Arguments
Name Description
siteId - ID!

Example

Query
mutation removeSite($accountId:ID!, $siteId:ID!){
  site(accountId:$accountId) {
    removeSite(siteId:$siteId) {
      siteId
    }
  }
}
Variables
{"accountId": "123", "siteId": "456"}
Response
{"data": {"site": {"removeSite": {"siteId": "456"}}}}

updateSocketInterface

Response

Returns an UpdateSocketInterfacePayload

Arguments
Name Description
siteId - ID!
socketInterfaceId - SocketInterfaceIDEnum!
input - UpdateSocketInterfaceInput!

Example

Query
mutation updateSocketInterface(
  $accountId:ID!,
  $siteId: ID!,
  $socketInterfaceId: SocketInterfaceIDEnum!,
  $input:UpdateSocketInterfaceInput!
) {
  site(accountId:$accountId){
    updateSocketInterface(siteId:$siteId, socketInterfaceId: $socketInterfaceId, input:$input){
      siteId
      socketInterfaceId
    }
  }
}
Variables
{
  "accountId": "123",
  "siteId": "456",
  "socketInterfaceId": "INT_1",
  "input": {
    "destType": "CATO",
    "bandwidth": {"upstreamBandwidth": 100, "downstreamBandwidth": 100}
  }
}
Response
{
  "data": {
    "site": {
      "updateSocketInterface": {"siteId": "456", "socketInterfaceId": "INT_1"}
    }
  }
}

addNetworkRange

Response

Returns an AddNetworkRangePayload

Arguments
Name Description
lanSocketInterfaceId - ID!
input - AddNetworkRangeInput!

Example

Query
mutation addNetworkRange(
  $accountId:ID!,
  $lanSocketInterfaceId: ID!,
  $input:AddNetworkRangeInput!
) {
  site(accountId:$accountId){
    addNetworkRange(lanSocketInterfaceId:$lanSocketInterfaceId, input:$input){
      networkRangeId
    }
  }
}
Variables
{
  "accountId": "123",
  "lanSocketInterfaceId": "456",
  "input": {
    "name": "Printers",
    "rangeType": "Routed",
    "subnet": "123.0.1.0/30",
    "gateway": "123.0.0.2"
  }
}
Response
{"data": {"site": {"addNetworkRange": {"networkRangeId": "UzQ3MDcw"}}}}

updateNetworkRange

Response

Returns an UpdateNetworkRangePayload

Arguments
Name Description
networkRangeId - ID!
input - UpdateNetworkRangeInput!

Example

Query
mutation updateNetworkRange(
  $accountId:ID!,
  $networkRangeId: ID!,
  $input:UpdateNetworkRangeInput!
) {
  site(accountId:$accountId){
    updateNetworkRange(networkRangeId:$networkRangeId, input:$input){
      networkRangeId
    }
  }
}
Variables
{"accountId": "123", "networkRangeId": "UzQ3MDcw", "input": {"name": "Devs"}}
Response
{"data": {"site": {"updateNetworkRange": {"networkRangeId": "UzQ3MDcw"}}}}

removeNetworkRange

Response

Returns a RemoveNetworkRangePayload

Arguments
Name Description
networkRangeId - ID!

Example

Query
mutation removeNetworkRange(
  $accountId:ID!,
  $networkRangeId: ID!,
) {
  site(accountId:$accountId){
    removeNetworkRange(networkRangeId:$networkRangeId){
      networkRangeId
    }
  }
}
Variables
{"accountId": "123", "networkRangeId": "UzQ3MDcw"}
Response
{"data": {"site": {"removeNetworkRange": {"networkRangeId": "UzQ3MDcw"}}}}

updateHa

Response

Returns an UpdateHaPayload

Arguments
Name Description
siteId - ID!
input - UpdateHaInput!

Example

Query
mutation updateHa($accountId:ID!,$siteId: ID!, $input: UpdateHaInput!) {
  site(accountId:$accountId){
    updateHa(siteId:$siteId, input:$input){
      siteId
    }
  }
}
Variables
{
  "accountId": "123",
  "siteId": "456",
  "input": {
    "primaryManagementIp": "123.0.0.231",
    "secondaryManagementIp": "123.0.0.232",
    "vrid": 123
  }
}
Response
{"data": {"site": {"updateHa": {"siteId": "456"}}}}

addStaticHost

Response

Returns an AddStaticHostPayload

Arguments
Name Description
siteId - ID!
input - AddStaticHostInput!

Example

Query
mutation addStaticHost($accountId:ID!,$siteId: ID!, $input: AddStaticHostInput!) {
  site(accountId:$accountId){
    addStaticHost(siteId:$siteId, input:$input){
      hostId
    }
  }
}
Variables
{
  "accountId": "123",
  "siteId": "456",
  "input": {"name": "Printer", "ip": "123.0.0.10"}
}
Response
{"data": {"site": {"addStaticHost": {"hostId": "789"}}}}

updateStaticHost

Response

Returns an UpdateStaticHostPayload

Arguments
Name Description
hostId - ID!
input - UpdateStaticHostInput!

Example

Query
mutation updateStaticHost($accountId:ID!,$hostId: ID!, $input: UpdateStaticHostInput!) {
  site(accountId:$accountId){
    updateStaticHost(hostId:$hostId, input:$input){
      hostId
    }
  }
}
Variables
{
  "accountId": "123",
  "hostId": "789",
  "input": {"name": "Printer", "ip": "123.0.0.11"}
}
Response
{"data": {"site": {"updateStaticHost": {"hostId": "789"}}}}

removeStaticHost

Response

Returns a RemoveStaticHostPayload

Arguments
Name Description
hostId - ID!

Example

Query
mutation removeStaticHost($accountId:ID!,$hostId: ID!) {
  site(accountId:$accountId){
    removeStaticHost(hostId:$hostId){
      hostId
    }
  }
}
Variables
{"accountId": "123", "hostId": "789"}
Response
{"data": {"site": {"removeStaticHost": {"hostId": "789"}}}}

Types

AccountDataPayload

Fields
Field Name Description
id - ID!
name - String!
subdomain - String!
Example
{
  "id": "4",
  "name": "abc123",
  "subdomain": "xyz789"
}

AccountMetrics

Fields
Field Name Description
id - ID Unique Identifier of Account.
from - DateTime Starting time
to - DateTime Ending time
granularity - Int The size of a single time bucket in seconds
sites - [SiteMetrics!] Site connectivity metrics for the requested sites.
Arguments
siteIDs - [ID!]

A list of unique IDs for each site. If specified, only sites in this list are returned. Otherwise, all sites are returned.

users - [SiteMetrics!] Connectivity metrics for the requested users connecting remotely with the Client. Doesn’t include user traffic behind a site.
Arguments
userIDs - [ID!]

A list of unique IDs for each user. If specified, only users in this list are returned. Otherwise, no user metrics are returned.

timeseries - [Timeseries!]
Arguments
buckets - Int

number of buckets, defaults to 10, max 1000

Example
{
  "id": 4,
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "granularity": 123,
  "sites": [SiteMetrics],
  "users": [SiteMetrics],
  "timeseries": [Timeseries]
}

AccountRolesResult

Fields
Field Name Description
items - [RBACRole!]!
total - Int!
Example
{"items": [RBACRole], "total": 987}

AccountSnapshot

Fields
Field Name Description
id - ID Unique Identifier of Account
sites - [SiteSnapshot!] Sites includes information about online as well as offline sites
Arguments
siteIDs - [ID!]

List of Unique Site Identifiers. If specified, only sites in list will be returned

users - [UserSnapshot!] VPN users information includes only connected users by default (Unlike sites), unless specific ID is requested
Arguments
userIDs - [ID!]

request specific IDs, regardless of if connected or not

timestamp - DateTime
Example
{
  "id": 4,
  "sites": [SiteSnapshot],
  "users": [UserSnapshot],
  "timestamp": "2007-12-03T10:15:30Z"
}

AccountType

Values
Enum Value Description

SYSTEM

REGULAR

RESELLER

ALL

Example
"SYSTEM"

AddAdminInput

Fields
Input Field Description
firstName - String!
lastName - String!
email - String!
passwordNeverExpires - Boolean!
mfaEnabled - Boolean!
managedRoles - [UpdateAdminRoleInput!]
resellerRoles - [UpdateAdminRoleInput!]
Example
{
  "firstName": "xyz789",
  "lastName": "xyz789",
  "email": "xyz789",
  "passwordNeverExpires": false,
  "mfaEnabled": false,
  "managedRoles": [UpdateAdminRoleInput],
  "resellerRoles": [UpdateAdminRoleInput]
}

AddAdminPayload

Fields
Field Name Description
adminID - ID!
Example
{"adminID": 4}

AddNetworkRangeInput

Fields
Input Field Description
name - String!
rangeType - SubnetType!
subnet - IPSubnet!
translatedSubnet - IPSubnet
localIp - IPAddress Only relevant for NATIVE, SECONDARY_NATIVE, DIRECT_ROUTE, VLAN rangeType
gateway - IPAddress Only relevant for ROUTED_ROUTE rangeType
vlan - Int Only relevant for VLAN network rangeType
azureFloatingIp - IPAddress Only relevant for AZURE HA sites
dhcpSettings - NetworkDhcpSettingsInput Only relevant for NATIVE, VLAN rangeType
Example
{
  "name": "xyz789",
  "rangeType": "Routed",
  "subnet": IPSubnet,
  "translatedSubnet": IPSubnet,
  "localIp": IPAddress,
  "gateway": IPAddress,
  "vlan": 987,
  "azureFloatingIp": IPAddress,
  "dhcpSettings": NetworkDhcpSettingsInput
}

AddNetworkRangePayload

Fields
Field Name Description
networkRangeId - ID!
Example
{"networkRangeId": "4"}

AddSiteLocationInput

Fields
Input Field Description
countryCode - String!
stateCode - String
timezone - String!
address - String
Example
{
  "countryCode": "xyz789",
  "stateCode": "xyz789",
  "timezone": "abc123",
  "address": "xyz789"
}

AddSocketSiteInput

Fields
Input Field Description
name - String!
connectionType - SiteConnectionTypeEnum!
siteType - SiteType!
description - String
nativeNetworkRange - IPSubnet!
translatedSubnet - IPSubnet
siteLocation - AddSiteLocationInput!
Example
{
  "name": "xyz789",
  "connectionType": "SOCKET_X1500",
  "siteType": "BRANCH",
  "description": "abc123",
  "nativeNetworkRange": IPSubnet,
  "translatedSubnet": IPSubnet,
  "siteLocation": AddSiteLocationInput
}

AddSocketSitePayload

Fields
Field Name Description
siteId - ID!
Example
{"siteId": 4}

AddStaticHostInput

Fields
Input Field Description
name - String!
ip - IPAddress!
macAddress - String
Example
{
  "name": "abc123",
  "ip": IPAddress,
  "macAddress": "abc123"
}

AddStaticHostPayload

Fields
Field Name Description
hostId - ID!
Example
{"hostId": "4"}

Admin

Description

A CC2 administrator

Fields
Field Name Description
id - ID!
version - String!
role - UserRole
firstName - String
lastName - String
email - String
creationDate - DateTime
modifyDate - DateTime
status - OperationalStatus
passwordNeverExpires - Boolean
mfaEnabled - Boolean
nativeAccountID - ID
allowedItems - [Entity!]
presentUsageAndEvents - Boolean
managedRoles - [AdminRole!]
resellerRoles - [AdminRole!]
Example
{
  "id": "4",
  "version": "abc123",
  "role": "OWNER",
  "firstName": "abc123",
  "lastName": "abc123",
  "email": "xyz789",
  "creationDate": "2007-12-03T10:15:30Z",
  "modifyDate": "2007-12-03T10:15:30Z",
  "status": "active",
  "passwordNeverExpires": false,
  "mfaEnabled": true,
  "nativeAccountID": 4,
  "allowedItems": [Entity],
  "presentUsageAndEvents": false,
  "managedRoles": [AdminRole],
  "resellerRoles": [AdminRole]
}

AdminRole

Fields
Field Name Description
role - RBACRole!
allowedEntities - [Entity!]
allowedAccounts - [ID!]
Example
{
  "role": RBACRole,
  "allowedEntities": [Entity],
  "allowedAccounts": [4]
}

AdminsResult

Fields
Field Name Description
items - [Admin!]!
total - Int!
Example
{"items": [Admin], "total": 987}

AggregationType

Values
Enum Value Description

sum

count

count_distinct

distinct

avg

max

min

any

changes

uniq_set

Example
"sum"

AnnotationType

Values
Enum Value Description

popChange

The site connects to a different PoP

roleChange

Change for HA status role

remoteIPChange

The ISP IP address (remote IP) changed

generic

Other events that are included in annotations
Example
"popChange"

ApnMethod

Values
Enum Value Description

METHOD_UNKNOWN

METHOD_AUTO

METHOD_MANUAL

Example
"METHOD_UNKNOWN"

AppStats

Fields
Field Name Description
id - ID
from - DateTime
to - DateTime
total - Int
totals - Map
records - [AppStatsRecord!]
Arguments
limit - Int
from - Int
Example
{
  "id": "4",
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "total": 987,
  "totals": Map,
  "records": [AppStatsRecord]
}

AppStatsField

Fields
Field Name Description
name - AppStatsFieldName!
value - Value!
Example
{"name": "app", "value": StringValue}

AppStatsFieldName

Values
Enum Value Description

app

the cloud application identifier

application

the cloud application name

new_app

new cloud application identifier

discovered_app

traffic

the total sum of upstream and downstream data in bytes

upstream

data uploaded to cloud applications

downstream

data downloaded from cloud applications

risk_score

the application risk score assigned by Cato

risk_level

sanctioned

cloud applications approved for use and managed by the organization

hq_location

the country in which the registered application headquarteres is located

is_cloud_app

indicates whether the application is considered cloud app/SaaS app

category

the cloud application category

description

ip

subnet

domain

dest_ip

src_site_id

src_site_name

Source site or VPN user

site_country

site_state

vpn_user_id

flows_created

dest_site

Destination Site or VPN user ID (proto)

dest_is_site_or_vpn

Destination Site or VPN user

dest_site_id

Destination Site or VPN user ID (DB)

dest_site_name

Destination Site or VPN user name

traffic_direction

Traffic direction

device_name

PC or device name

ad_name

Active Directory name

src_ip

IP for host or VPN client

socket_interface

Name for Socket interface

src_is_site_or_vpn

Traffic is site or VPN client
Example
"app"

AppStatsFilter

Fields
Input Field Description
fieldName - AppStatsFieldName!
operator - FilterOperator!
values - [String!]!
Example
{
  "fieldName": "app",
  "operator": "is",
  "values": ["xyz789"]
}

AppStatsRecord

Fields
Field Name Description
fields - [AppStatsField!]
fieldsUnitTypes - [UnitType!]
fieldsMap - Map fields in map format (see Map scalar)
trends - Map
prevTimeFrame - Map
flatFields - [String!] Simplified fields, as array of name value tuples, e.g: [ [ "name", "val" ], [ "name2", "val2" ] ... ]
Example
{
  "fields": [AppStatsField],
  "fieldsUnitTypes": ["bytes"],
  "fieldsMap": Map,
  "trends": Map,
  "prevTimeFrame": Map,
  "flatFields": ["xyz789"]
}

AppStatsSort

Fields
Input Field Description
fieldName - AppStatsFieldName!
order - DirectionEnum!
Example
{"fieldName": "app", "order": "asc"}

AppStatsTimeSeries

Fields
Field Name Description
id - ID
from - DateTime
to - DateTime
granularity - Int
timeseries - [Timeseries!]
Arguments
buckets - Int!
Example
{
  "id": "4",
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "granularity": 987,
  "timeseries": [Timeseries]
}

AuditFeed

Fields
Field Name Description
from - DateTime
to - DateTime
marker - String
fetchedCount - Int!
hasMore - Boolean
accounts - [AuditFeedAccountRecords]
Example
{
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "marker": "xyz789",
  "fetchedCount": 987,
  "hasMore": true,
  "accounts": [AuditFeedAccountRecords]
}

AuditFeedAccountRecords

Fields
Field Name Description
id - ID
records - [AuditRecord!]
Arguments
fieldNames - [AuditFieldName!]
Example
{"id": 4, "records": [AuditRecord]}

AuditField

Fields
Field Name Description
name - String!
value - Value!
Example
{
  "name": "abc123",
  "value": StringValue
}

AuditFieldFilterInput

Fields
Input Field Description
fieldName - FieldNameInput!
operator - ElasticOperator! Use AuditFieldName for audits
values - [String!]
Example
{
  "fieldName": FieldNameInput,
  "operator": "is",
  "values": ["xyz789"]
}

AuditFieldName

Values
Enum Value Description

admin

The admin whose action generated the record

apiKey

The api key whose action generated the record

model_name

The name of the object that was affected, e.g. 'My Site'

admin_id

The ID of the admin whose action generated the record

module

Less granular than model_name, a general marker of the modified area: administration, configuration, security

audit_creation_type

insertion_date

Time the record was committed to storage

change_type

the nature of the change: CREATED, DELETED, MODIFIED, ENABLED, DISABLED, SKIPPED

creation_date

Time the record was created

model_type

The type of object that was affected. e.g. Site, Socket, SocketInterface

account

The name of the account on which the record was created

account_id

The id of the account on which the record was created
Example
"admin"

AuditRecord

Description

Represents a single event in the audit database

Fields
Field Name Description
admin - Entity
apiKey - Entity
object - Entity
account - EntityInfo
time - DateTime
fields - [AuditField!] All fields in the audit record (including the admin and object)
fieldsMap - Map fields in map format (see Map scalar)
flatFields - [String!] Simplified fields, as array of name value tuples, e.g: [ [ "name", "val" ], [ "name2", "val2" ] ... ]
Example
{
  "admin": Entity,
  "apiKey": Entity,
  "object": Entity,
  "account": EntityInfo,
  "time": "2007-12-03T10:15:30Z",
  "fields": [AuditField],
  "fieldsMap": Map,
  "flatFields": ["xyz789"]
}

Boolean

Description

The Boolean scalar type represents true or false.

CellularDisconnectionReason

Values
Enum Value Description

REASON_NONE

REASON_TIMEOUT

Example
"REASON_NONE"

CellularInterface

Fields
Field Name Description
networkType - CellularNetworkType 2G, 3G, or 4G
simSlotId - Int Shows the currently active SIM slot; the other slot is in standby. Slot 1 is active by default.
modemStatus - CellularModemStatus Represents the current status of the modem. Valid values are Error, OK, or Unknown.
isModemConnected - Boolean! Indicates if the cellular modem is currently connected to the internet.
iccid - String Unique identifier (20-digit number) for the modem.
imei - String Unique identifier (15-digit number) for a specific SIM.
operatorName - String Displays the operator or carrier name, such as Verizon.
isModemSuspended - Boolean! Indicates if the modem is currently suspended.
apn - String Represents the Access Point Name (e.g., uwap.orange.co.il). Configurable from Socket WebUI or SIM switch.
apnSelectionMethod - ApnMethod Determines how the APN is selected. Valid values are Auto or Manual (configurable in WebUI).
signalStrength - String Represents the signal strength of the cellular connection, in units of calculation.
isRoamingAllowed - Boolean! Indicates whether roaming is enabled.
simNumber - String The phone number associated with the SIM.
disconnectionReason - CellularDisconnectionReason Displays the reason for the modem disconnecting. Valid values are 0 (No reason provided) or 1 (The session timed out).
isSimSlot1Detected - Boolean! Indicates whether a SIM is detected in the first slot.
isSimSlot2Detected - Boolean! Indicates whether a SIM is detected in the second slot.
Example
{
  "networkType": "TYPE_UNKNOWN",
  "simSlotId": 987,
  "modemStatus": "STATUS_UNKNOWN",
  "isModemConnected": false,
  "iccid": "xyz789",
  "imei": "abc123",
  "operatorName": "xyz789",
  "isModemSuspended": false,
  "apn": "abc123",
  "apnSelectionMethod": "METHOD_UNKNOWN",
  "signalStrength": "xyz789",
  "isRoamingAllowed": false,
  "simNumber": "xyz789",
  "disconnectionReason": "REASON_NONE",
  "isSimSlot1Detected": true,
  "isSimSlot2Detected": true
}

CellularModemStatus

Values
Enum Value Description

STATUS_UNKNOWN

STATUS_OK

STATUS_ERROR

Example
"STATUS_UNKNOWN"

CellularNetworkType

Values
Enum Value Description

TYPE_UNKNOWN

TYPE_2G

TYPE_3G

TYPE_4G

Example
"TYPE_UNKNOWN"

ConnectivityStatus

Values
Enum Value Description

connected

Connected to the Cato Cloud

disconnected

Disconnected from the Cato Cloud
Example
"connected"

DateTime

Description

2006-01-02T15:04:05Z07:00 (RFC3339)

Example
"2007-12-03T10:15:30Z"

DateValue

Fields
Field Name Description
date - DateTime
Example
{"date": "2007-12-03T10:15:30Z"}

DeviceSnapshot

Fields
Field Name Description
id - ID Unique internal Cato ID for the Socket
name - String Name of the device
identifier - String Unique identifier for the device
connected - Boolean A boolean value that indicates if the site is connected to the Cato Cloud
haRole - String Shows if this is the primary or secondary Socket in high availability mode
interfaces - [InterfaceSnapshot!] Snapshot data for outbound facing interfaces
lastConnected - DateTime The last time the device was seen
lastDuration - Int The uptime of the last tunnel from this device (or current), in seconds
connectedSince - DateTime For connected devices (this somewhat overlaps to last duration)
lastPopID - Int The ID of the PoP that the Socket is connected to
lastPopName - String The PoP name that the Socket is connected to
recentConnections - [RecentConnection!] Data related to the most recent completed traffic flows
type - String Shows the Socket model or vSocket type
socketInfo - SocketInfo Shows data related to the Socket, such as version and serial number
interfacesLinkState - [InterfaceLinkState!] Information of the link state of various interfaces in the devices. Unlike the interfacess field, it contains all links of the device, not just the outbound facing ones
osType - String Operating system of the Device.
osVersion - String Version of the Socket operating system
version - String Device version
versionNumber - Int Device major version
releaseGroup - String Shows the release group for the site
mfaExpirationTime - Int Shows the amount of time remaining before the MFA token expires
mfaCreationTime - Int The time the mfa cookie (for sdp users) was created
internalIP - String Device's internal IP in the account's routing table
Example
{
  "id": 4,
  "name": "abc123",
  "identifier": "xyz789",
  "connected": true,
  "haRole": "xyz789",
  "interfaces": [InterfaceSnapshot],
  "lastConnected": "2007-12-03T10:15:30Z",
  "lastDuration": 987,
  "connectedSince": "2007-12-03T10:15:30Z",
  "lastPopID": 123,
  "lastPopName": "abc123",
  "recentConnections": [RecentConnection],
  "type": "xyz789",
  "socketInfo": SocketInfo,
  "interfacesLinkState": [InterfaceLinkState],
  "osType": "abc123",
  "osVersion": "xyz789",
  "version": "xyz789",
  "versionNumber": 123,
  "releaseGroup": "xyz789",
  "mfaExpirationTime": 123,
  "mfaCreationTime": 123,
  "internalIP": "xyz789"
}

DhcpType

Values
Enum Value Description

DHCP_RELAY

DHCP_RANGE

ACCOUNT_DEFAULT

DHCP_DISABLED

Example
"DHCP_RELAY"

Dimension

Fields
Input Field Description
fieldName - AppStatsFieldName!
Example
{"fieldName": "app"}

DimensionData

Fields
Field Name Description
label - String! Type of the dimension
value - String String value of the dimension
Example
{
  "label": "abc123",
  "value": "xyz789"
}

DimensionKey

Fields
Field Name Description
fieldName - String! Dimension field
value - String String value of the dimension
Example
{
  "fieldName": "xyz789",
  "value": "abc123"
}

DirectionEnum

Values
Enum Value Description

asc

desc

Example
"asc"

DirectionInput

Values
Enum Value Description

asc

desc

Example
"asc"

ElasticOperator

Description

Search operators on ElasticSearch. Between operators are applicable only to numeric fields Note that not operators are slower

Values
Enum Value Description

is

is_not

in

not_in

exists

not_exists

between

not_between

Example
"is"

Entity

Fields
Field Name Description
id - ID!
name - String
type - EntityType!
Example
{
  "id": "4",
  "name": "abc123",
  "type": "country"
}

EntityInfo

Fields
Field Name Description
entity - Entity!
description - String!
helperFields - Map!
Example
{
  "entity": Entity,
  "description": "abc123",
  "helperFields": Map
}

EntityInput

Fields
Input Field Description
id - ID!
name - String
type - EntityType!
Example
{
  "id": 4,
  "name": "abc123",
  "type": "country"
}

EntityLookupResult

Fields
Field Name Description
items - [EntityInfo!]!
total - Int
Example
{"items": [EntityInfo], "total": 987}

EntityType

Values
Enum Value Description

country

Geographical and political entity recognized internationally

countryState

Represents a state or territory within a country. It is a sub-division of the country

timezone

Time zone, which is a geographical region where clocks are set to the same time

site

A reference to a configured Site within Account

host

A reference to the configured Host within Site

any

Any entity (matches everything)

account

A reference to a configured Account under reseller

networkInterface

A reference to the configured Network Interface within Site

vpnUser

A reference to the configured VPN User within Account

admin

An account administrator (user in Cato Console)

localRouting

A reference to Local Routing Rule within Site

lanFirewall

A reference to LAN Firewall Rule within Site

siteRange

union of the globalRange and a Subnet

simpleService

l4 services for LAN firewall rules

availableSiteUsage

Site licenses available for use

availablePooledUsage

Pooled licenses available for use

dhcpRelayGroup

A reference to DHCP Relay Group within account

portProtocol

Combination of protocol (TCP, UDP, TCP/UDP, ICMP) and port number

groupSubscription

mailingListSubscription

webhookSubscription

Example
"country"

EventFeedFieldFilterInput

Fields
Input Field Description
fieldName - EventFeedFilterFieldName!
operator - EventFeedFilterOperator! Use event_type and event_sub_type for events
values - [String!]
Example
{
  "fieldName": "event_sub_type",
  "operator": "is",
  "values": ["abc123"]
}

EventFeedFilterFieldName

Values
Enum Value Description

event_sub_type

Sub-type for Routing, Security, Connectivity, System or Sockets Management event

event_type

Routing, Security, Connectivity, System or Sockets Management event
Example
"event_sub_type"

EventFeedFilterOperator

Description

Search operators on Event Feed

Values
Enum Value Description

is

is_not

in

not_in

Example
"is"

EventField

Fields
Field Name Description
name - EventFieldName!
value - Value!
Example
{"name": "src_site", "value": StringValue}

EventFieldName

Values
Enum Value Description

src_site

Site or VPN user initiating the transaction

src_site_id

dest_site

Target Site or VPN user

src_or_dest_site_id

Source or destination site or VPN user ID. This field can only be used in filter.

rule

Rule ID in security events

ISP_name

Remote ISP name

socket_interface

Name for Socket interface

custom_category

directory_host_name

LDAP event, host name

dest_port

Internet traffic, destination server port

bgp_peer_asn

BGP ASN for remote peer

user_reference_id

The reference number of a miscategorization event

src_port

Internal port number

link_health_pkt_loss

Data that measures the packet loss for a specific link

pop_name

Name of PoP for event

host_ip

event_message

Cato's description of the event

src_site_name

Source site or VPN user

domain_name

SSL SNI, HTTPhost name, DNSname

dest_ip

Internet traffic, destination server IP

file_hash

Malware event, file hash

src_isp_ip

ISP IP for site or VPN client

authentication_type

Examples: MFA or password

rule_name

Firewall rule name

directory_sync_result

LDAP event, sync with DC results

host_mac

threat_type

Type of malware event

threat_verdict

Result of malware event

device_name

PC or device name

link_type

Link type – Cato, Alt. WAN or LAG

login_type

User portal or VPN client (VPN or site traffic)

configured_host_name

Host name (hosts with static IP)

internalId

directory_sync_type

LDAP event, sync with DC

vpn_user_email

User email

client_class

Type of process generating this traffic

incident_aggregation

Incident aggregation

socket_reset

Hardware or software Socket reset

user_name

User name

client_version

Socket or VPN client version

file_size

Malware event, file size

registration_code

bgp_error_code

BGP disconnect error message

bgp_peer_description

Description for BGP neighbor

threat_name

Name of malware event

qos_reported_time

Time QoS event started

ip_protocol

Network protocol for this event

bgp_cato_asn

BGP ASN for Cato peer

src_ip

IP for host or VPN client

threat_reference

Link to external malware reference

action

Firewall, QoS or LAG action

windows_domain_name

risk_level

Malware event, risk level

socket_old_version

Socket upgrade, old version number

link_health_latency

Data that measures the latency for a specific link

tunnel_protocol

Protocol for the tunnel

socket_new_version

Socket upgrade, new version number

link_health_jitter

Data that measures the jitter for a specific link

upgrade_start_time

Upgrade started at:

bgp_cato_ip

BGP IP for Cato peer

categories

Cato Networks Category

rule_id

socket_role

targets_cardinality

Amount of targets (servers) for a given incident

upgrade_initiated_by

Upgrade initiated by

dest_is_site_or_vpn

Site or VPN user

bgp_peer_ip

BGP IP for remote peer

src_is_site_or_vpn

Traffic is site or VPN client

ad_name

Active Directory name

user_awareness_method

User Awareness Query Method

link_health_is_congested

Data that measures the congestion for a specific link

subnet_name

Name for subnet

os_version

Version for host OS or tunnel device

event_sub_type

Sub-type for Routing, Security, Connectivity, System or Sockets Management event

os_type

Host OS or tunnel device

traffic_direction

Inbound or outbound

bgp_suberror_code

BGP disconnect error message

bgp_route_cidr

CIDR for BGP route

incident_id

Incident identifier

application

App used in Internet Firewall

upgrade_end_time

Upgrade ended at:

socket_interface_id

Socket interface ID

custom_categories

Custom category for the account

src_country

Country based on public IP

src_country_code

Country code based on public IP

event_count

Count for events often repeated

file_name

Malware event, file name

directory_ip

LDAP event, IP for DC

time

Time of event

url

URL for Internet traffic

dest_country

Internet traffic, destination server location

dest_country_code

Internet traffic, destination server location code

flows_cardinality

Amount of flows for a given incident

dest_site_name

Name of site or VPN user

event_type

Routing, Security, Connectivity, System or Sockets Management event

account_id

Account ID

signature_id

Signature ID

client_cert_expires

Client certificate expiration date

client_cert_name

Name of client Certificate

is_sanctioned_app

Is sanctioned app matched

application_class

Name of application class

app_activity

Name of application activity

device_posture_profiles

Device posture profiles

full_path_url

Full path URL application activity

application_risk

Application risk score

mitre_attack_techniques

Mitre attack techniques

mitre_attack_subtechniques

Mitre attack subtechniques

mitre_attack_tactics

Mitre attack tactics

indicator

Indicator

connector_type

Connector Type

connector_name

Connector Name

parent_connector_name

file_type

dlp_profiles

matched_data_types

severity

owner

Owner

sender

No longer supported

collaborators

Collaborators

recipients

No longer supported

email_subject

Email Subject

sharing_scope

Sharing Scope

dns_protection_category

DNS Protection Category

final_object_status

object_name

object_type

alert_id

vendor

vendor_user_id

status

classification

quarantine_folder_path

title

recommended_actions

pid

parent_pid

process_path

logged_in_user

http_request_method

xff

dns_query

DNS Query

key_name

api_type

api_name

app_stack

Related Apps

tls_certificate_error

TLS Certificate Error

tls_version

TLS Version

tls_error_type

TLS Error Type

tls_error_description

TLS Error Description

cato_app

Cato App

prompt_action

Prompt Page Selected Action

device_id

Unique Cato ID for devices

visible_device_id

Unique Cato Visible ID for devices

auth_method

Connectivity authentication method: unauthenticated, OATH2, LDAP or VPN

bypass_method

Always-On Bypass Method

bypass_duration_sec

Always-On Bypass Duration In Seconds

bypass_reason

Always-On Bypass Reason

sign_in_event_types

Sign In Types

tenant_id

Tenant Id

tenant_name

Tenant Name

user_agent

User Agent

vendor_event_id

Vendor Event Id

vendor_device_id

Vendor Device Id

vendor_device_name

Vendor Device Name

is_compliant

Is Compliant

is_managed

Is Managed

trust_type

Trust Type

trust_level

Trust Level

dlp_scan_types

Data Classifiers

network_access

Network Access

analyst_verdict

Analyst Verdict

criticality

Criticality

indication

Indication

producer

Producer

story_id

Story Id

raw_data

Raw Data
Example
"src_site"

EventRecord

Fields
Field Name Description
time - DateTime
fieldsMap - Map fields in map format (see Map scalar)
flatFields - [String!] Simplified fields, as array of name value tuples, e.g: [ [ "name", "val" ], [ "name2", "val2" ] ... ]
Example
{
  "time": "2007-12-03T10:15:30Z",
  "fieldsMap": Map,
  "flatFields": ["abc123"]
}

Events

Fields
Field Name Description
id - ID
from - DateTime
to - DateTime
total - Int
totals - Map
records - [EventsRecord!]
Arguments
limit - Int
from - Int
Example
{
  "id": 4,
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "total": 987,
  "totals": Map,
  "records": [EventsRecord]
}

EventsDimension

Fields
Input Field Description
fieldName - EventFieldName!
Example
{"fieldName": "src_site"}

EventsFeedAccountRecords

Fields
Field Name Description
id - ID
errorString - String
records - [EventRecord!]
Arguments
fieldNames - [EventFieldName!]
Example
{
  "id": 4,
  "errorString": "abc123",
  "records": [EventRecord]
}

EventsFeedData

Fields
Field Name Description
marker - String
fetchedCount - Int!
accounts - [EventsFeedAccountRecords]
Example
{
  "marker": "xyz789",
  "fetchedCount": 987,
  "accounts": [EventsFeedAccountRecords]
}

EventsFilter

Fields
Input Field Description
fieldName - EventFieldName!
operator - FilterOperator!
values - [String!]!
Example
{
  "fieldName": "src_site",
  "operator": "is",
  "values": ["abc123"]
}

EventsMeasure

Fields
Input Field Description
fieldName - EventFieldName!
aggType - AggregationType!
trend - Boolean
Example
{"fieldName": "src_site", "aggType": "sum", "trend": true}

EventsRecord

Fields
Field Name Description
fields - [EventField!]
fieldsUnitTypes - [UnitType!]
fieldsMap - Map fields in map format (see Map scalar)
trends - Map
prevTimeFrame - Map
flatFields - [String!] Simplified fields, as array of name value tuples, e.g: [ [ "name", "val" ], [ "name2", "val2" ] ... ]
Example
{
  "fields": [EventField],
  "fieldsUnitTypes": ["bytes"],
  "fieldsMap": Map,
  "trends": Map,
  "prevTimeFrame": Map,
  "flatFields": ["xyz789"]
}

EventsSort

Fields
Input Field Description
fieldName - EventFieldName!
order - DirectionEnum!
Example
{"fieldName": "src_site", "order": "asc"}

EventsTimeSeries

Fields
Field Name Description
id - ID
from - DateTime
to - DateTime
granularity - Int
timeseries - [Timeseries!]
Arguments
buckets - Int!
Example
{
  "id": 4,
  "from": "2007-12-03T10:15:30Z",
  "to": "2007-12-03T10:15:30Z",
  "granularity": 123,
  "timeseries": [Timeseries]
}

FieldNameInput

Description

FieldName for the different types of FieldName inputs Use the EventFieldName for events, and AuditFieldName for audit

Fields
Input Field Description
EventFieldName - EventFieldName
AuditFieldName - AuditFieldName
Example
{"EventFieldName": "src_site", "AuditFieldName": "admin"}

FilterOperator

Values
Enum Value Description

is

is_not

in

not_in

exists

not_exists

between

not_between

gt

gte

lt

lte

Example
"is"

Float

Description

The Float scalar type represents signed double-precision fractional values as specified by IEEE 754.

Example
987.65

GetAdminPayload

Fields
Field Name Description
id - ID!
firstName - String!
lastName - String!
email - String!
creationDate - String!
passwordNeverExpires - Boolean!
mfaEnabled - Boolean!
managedRoles - [AdminRole!]
resellerRoles - [AdminRole!]
Example
{
  "id": "4",
  "firstName": "xyz789",
  "lastName": "xyz789",
  "email": "abc123",
  "creationDate": "abc123",
  "passwordNeverExpires": false,
  "mfaEnabled": false,
  "managedRoles": [AdminRole],
  "resellerRoles": [AdminRole]
}

HaReadiness

Values
Enum Value Description

ready

not_ready

Example
"ready"

HaStatus

Description

Basic Site Ha readiness information

Fields
Field Name Description
readiness - HaReadiness
wanConnectivity - HaSubStatus
keepalive - HaSubStatus
socketVersion - HaSubStatus
Example
{
  "readiness": "ready",
  "wanConnectivity": "ok",
  "keepalive": "ok",
  "socketVersion": "ok"
}

HaSubStatus

Values
Enum Value Description

ok

fail

Example
"ok"

ID

Description

The ID scalar type represents a unique identifier, often used to refetch an object or as key for a cache. The ID type appears in a JSON response as a String; however, it is not intended to be human-readable. When expected as an input type, any string (such as "4") or integer (such as 4) input value will be accepted as an ID.

Example
4

IPAddress

Example
IPAddress

IPInfo

Description

A general structure to contain IP detailed information

Fields
Field Name Description
ip - String IP address of the link
countryCode - String Geolocation ISO country code
countryName - String Geolocation country name
city - String Geolocation city
state - String Geolocation state
provider - String ISP Internet provider
latitude - Float Geolocation latitude for the ISP
longitude - Float Geolocation longitude for the ISP
Example
{
  "ip": "abc123",
  "countryCode": "abc123",
  "countryName": "xyz789",
  "city": "xyz789",
  "state": "abc123",
  "provider": "abc123",
  "latitude": 123.45,
  "longitude": 987.65
}

IPRange

Description

A from-to range (used for DHCP range, for example)

Example
IPRange

IPSecInfo

Description

Basic IPSec configuration information

Fields
Field Name Description
isPrimary - Boolean For HA configurations, when this boolean value is true, this the primary IPsec firewall or routing device
catoIP - String The source IP address for the IPsec tunnel in the Cato Cloud
remoteIP - String The destination IP address for the IPsec tunnel (in the site)
ikeVersion - Int Shows 1 for IKEv1 and 2 for IKEv2
Example
{
  "isPrimary": true,
  "catoIP": "abc123",
  "remoteIP": "xyz789",
  "ikeVersion": 987
}

IPSubnet

Example
IPSubnet

Int

Description

The Int scalar type represents non-fractional signed whole numeric values. Int can represent values between -(2^31) and 2^31 - 1.

Example
987

InterfaceInfo

Description

Basic Socket Interface configuration information

Fields
Field Name Description
id - ID! ID for the Socket port in the Socket WebUI Monitor tab
name - String Name for the port in the Cato Management Application
upstreamBandwidth - Int Maximum allowed bandwidth on this port, for traffic from the site to the Cato Cloud
downstreamBandwidth - Int Maximum allowed bandwidth for traffic on this port, from the Cato Cloud to the site
destType - String The destination type configured to the Socket interface
Example
{
  "id": "4",
  "name": "xyz789",
  "upstreamBandwidth": 987,
  "downstreamBandwidth": 123,
  "destType": "abc123"
}

InterfaceLinkState

Fields
Field Name Description
id - ID The ID for the specific Socket port, for example LAN1 or LAN2
up - Boolean When this boolean value is true, then the link for the port is up
mediaIn - Boolean When this boolean value is true, then a cable is connected to the Socket port
linkSpeed - String Shows the maximum bandwidth configured for the link
duplex - String Shows the duplex mode for the link
Example
{
  "id": "4",
  "up": true,
  "mediaIn": true,
  "linkSpeed": "abc123",
  "duplex": "abc123"
}

InterfaceMetrics

Fields
Field Name Description
metrics - Metrics Traffic data for the link
Arguments
toRate - Boolean

Normalize collected metrics as per-second values

name - String Link name in the Cato Management Application
timeseries - [Timeseries!] For site metrics, timeseries info field will include: siteID, interfaceName, for last mile metrics it will also include the destination last mile check
Arguments
buckets - Int
annotations - [TimeAnnotation!] Time stamp annotation that shows a time increment for a GUI
Arguments
types - [String!]
periods - [TimePeriod!] object that is a specific time duration
remoteIPInfo - IPInfo Data related to the link IP address, such as country code
remoteIP - String IP address of the PoP that the link is connected to
socketInfo - SocketInfo Data related to Socket and vSocket sites, such as serial number and Socket version. Applicable only for site
ipsecInfo - IPSecInfo Data related to IPsec sites, such as IKE version . Applicable only for site
interfaceInfo - InterfaceInfo Basic configuration information about the Socket interface . Applicable only for site
Example
{
  "metrics": Metrics,
  "name": "xyz789",
  "timeseries": [Timeseries],
  "annotations": [TimeAnnotation],
  "periods": [TimePeriod],
  "remoteIPInfo": IPInfo,
  "remoteIP": "abc123",
  "socketInfo": SocketInfo,
  "ipsecInfo": IPSecInfo,
  "interfaceInfo": InterfaceInfo
}

InterfaceSnapshot

Fields
Field Name Description
connected - Boolean Shows if the WAN link is connected to the PoP
id - ID Interface ID for the WAN link
name - String WAN link name in the Cato Management Application
physicalPort - Int Physical WAN port on the Socket
naturalOrder - Int Interface Natural order for WAN link
popName - String The name of the PoP that the WAN link is connected to
previousPopID - Int The ID of the PoP that the WAN link was connected to before the current one
previousPopName - String The name of the PoP that the WAN link was connected to before the current one
tunnelConnectionReason - String Reason that the tunnel required a new connection (for example, PoP or Socket restarted)
tunnelUptime - Int Number of seconds that the tunnel is connected to a PoP
tunnelRemoteIP - String IP address of the WAN ISP
tunnelRemoteIPInfo - IPInfo IP address, ISP, and geographical information related to the WAN ISP
type - String No longer supported
info - InterfaceInfo data about the WAN link that is configured in the Socket Configuration window for the site
cellularInterfaceInfo - CellularInterface Information about cellular (LTE) interface
Example
{
  "connected": true,
  "id": "4",
  "name": "xyz789",
  "physicalPort": 123,
  "naturalOrder": 123,
  "popName": "abc123",
  "previousPopID": 987,
  "previousPopName": "xyz789",
  "tunnelConnectionReason": "xyz789",
  "tunnelUptime": 123,
  "tunnelRemoteIP": "xyz789",
  "tunnelRemoteIPInfo": IPInfo,
  "type": "xyz789",
  "info": InterfaceInfo,
  "cellularInterfaceInfo": CellularInterface
}

LookupFilterInput

Fields
Input Field Description
filter - LookupFilterType
value - String
Example
{
  "filter": "filterByConnectionTypeFamily",
  "value": "xyz789"
}

LookupFilterType

Values
Enum Value Description

filterByConnectionTypeFamily

Custom filter to be used with Site entityLookup, to get only sites with one connection type, possible values: "SOCKET", "IPSEC", "vSOCKET", "PHYSICAL_SOCKET"

filterByConnectionType

Custom filter to be used with Site entityLookup, to get only sites with one connection type, possible values (there are more values that can supported): "SOCKET_X1500", "SOCKET_X1600", "SOCKET_X1700", "VSOCKET_VGX_ESX", "VSOCKET_VGX_AWS" "VSOCKET_VGX_AZURE" "SOCKET_X1600_LTE",

filterByAltWan

Custom filter to be used with Site entityLookup, to get only sites with Alt WAN, possible values: "true", "false",

filterByBackhaulingGW

Custom filter to be used with Site entityLookup, to get only sites that are configured as backhauling gateways, possible values: "true", "false",

filterByOffCloudTransportEnabled

Custom filter to be used with Site entityLookup, to get only sites that are configured as OffCloudTransportEnabled, possible values: "true", "false",
Example
"filterByConnectionTypeFamily"

Map

Description

A key value pairs object { "key1": "value1", "key2": "value2" }

Example
Map

Measure

Fields
Input Field Description
fieldName - AppStatsFieldName!
aggType - AggregationType!
trend - Boolean
Example
{"fieldName": "app", "aggType": "sum", "trend": true}

Metrics

Fields
Field Name Description
duration - Int total amount of time for the site data
granularity - Int duration in seconds for a single metrics bucket
bytesDownstream - Float total downstream traffic (from the Cato Cloud to the site)
bytesUpstream - Float total upstream traffic (from the site to the Cato Cloud)
bytesTotal - Float total traffic for the site
lostDownstream - Float number of packets lost for downstream traffic
lostDownstreamPcnt - Float percent of packet loss for downstream traffic
lostUpstream - Float number of packets lost for upstream traffic
lostUpstreamPcnt - Float percent of packet loss for upstream traffic
packetsDownstream - Float total downstream packets
packetsUpstream - Float total upstream packets
jitterUpstream - Float jitter for upstream traffic (difference in time delay in milliseconds (ms) between data packets)
jitterDownstream - Float jitter for downstream traffic (difference in time delay in milliseconds (ms) between data packets)
packetsDiscardedDownstream - Float total packets discarded for downstream traffic
packetsDiscardedUpstream - Float total packets discarded for upstream traffic
rtt - Int round-trip time from the site to the Cato Cloud
hostCount - Float The number of hosts in the tunnel. Relevant only for per site Metrics, ignored in per-interface metrics.
hostLimit - Float The configurable limit of the number of hosts in the tunnel. Relevant only for per site Metrics, ignored in per-interface metrics.
flowCount - Float The number of flows (connections) in the tunnel. Relevant only for per site Metrics, ignored in per-interface metrics.
Example
{
  "duration": 123,
  "granularity": 987,
  "bytesDownstream": 123.45,
  "bytesUpstream": 987.65,
  "bytesTotal": 987.65,
  "lostDownstream": 987.65,
  "lostDownstreamPcnt": 123.45,
  "lostUpstream": 987.65,
  "lostUpstreamPcnt": 123.45,
  "packetsDownstream": 987.65,
  "packetsUpstream": 987.65,
  "jitterUpstream": 123.45,
  "jitterDownstream": 123.45,
  "packetsDiscardedDownstream": 987.65,
  "packetsDiscardedUpstream": 987.65,
  "rtt": 987,
  "hostCount": 987.65,
  "hostLimit": 987.65,
  "flowCount": 987.65
}

NetworkDhcpSettingsInput

Fields
Input Field Description
dhcpType - DhcpType!
ipRange - IPRange
relayGroupId - ID
Example
{
  "dhcpType": "DHCP_RELAY",
  "ipRange": IPRange,
  "relayGroupId": "4"
}

OperationalStatus

Values
Enum Value Description

active

Passing traffic

disabled

Disabled in the Cato Management Application

locked

License has expired for this site and you can't configure it

new

After you create the site before it is connected to the Cato Cloud

pending_user_configuration

For VPN users only

pending_mfa_configuration

For VPN users only

pending_code_generation

For VPN users only
Example
"active"

PeriodType

Values
Enum Value Description

packetLoss

packet loss connectivity issue

missingData

missing data

passiveLink

interface in standby mode

active

traffic was seen

overlowed

some packets were queued

congested

some packets were discarded after queue timeout

lastmilePacketLoss

multiple last mile destinations measured packet loss

lastmileLatency

multiple last mile destinations measured large latency (greater than 500ms)

generic

unspecified period type

pop

period connected to specific pop instance
Example
"packetLoss"

ProtoType

Values
Enum Value Description

SOCKET_X1500

VSOCKET_VGX

IPSEC_HOST

IPSEC_CLIENT

IPSEC_V2

SOCKET_X1600

SOCKET_X1700

SOCKET_AWS1500

SOCKET_AZ1500

SOCKET_ESX1500

CROSS_CONNECT

SOCKET_X1600_LTE

Example
"SOCKET_X1500"

RBACRole

Fields
Field Name Description
id - ID!
name - String!
description - String
isPredefined - Boolean!
Example
{
  "id": "4",
  "name": "xyz789",
  "description": "abc123",
  "isPredefined": true
}

RecentConnection

Fields
Field Name Description
duration - Int The duration of the connection
interfaceName - String Name for the port in the Cato Management Application
deviceName - String Serial number for the Device
lastConnected - DateTime The last time this connection was detected (so lastConnected - duration is the start of the connection
popName - String The name of the PoP that the traffic flow was connected to
remoteIP - String IP address of the PoP that the link is connected to
remoteIPInfo - IPInfo IP address, ISP, and geographical information related to the PoP that the traffic flow was connected to
Example
{
  "duration": 123,
  "interfaceName": "xyz789",
  "deviceName": "abc123",
  "lastConnected": "2007-12-03T10:15:30Z",
  "popName": "xyz789",
  "remoteIP": "abc123",
  "remoteIPInfo": IPInfo
}

RemoveAdminPayload

Fields
Field Name Description
adminID - ID!
Example
{"adminID": 4}

RemoveNetworkRangePayload

Fields
Field Name Description
networkRangeId - ID!
Example
{"networkRangeId": 4}

RemoveSitePayload

Fields
Field Name Description
siteId - ID!
Example
{"siteId": "4"}

RemoveStaticHostPayload

Fields
Field Name Description
hostId - ID!
Example
{"hostId": "4"}

SiteConnectionTypeEnum

Values
Enum Value Description

SOCKET_X1500

SOCKET_X1600

SOCKET_X1700

SOCKET_ESX1500

SOCKET_AWS1500

SOCKET_AZ1500

SOCKET_X1600_LTE

Example
"SOCKET_X1500"

SiteInfo

Description

Basic Site configuration information

Fields
Field Name Description
name - String Name for the site
type - SiteType Site type in the Cato Management Application, such as branch office or datacenter
description - String User defined description of the site
countryCode - String Code for the Country that is the physical location of the site
region - String Geographical PoP region that the site is licensed to use
countryName - String Country that is the physical location of the site
isHA - Boolean When this boolean value is true, the site is enabled for high availability
connType - ProtoType The Connection Type field defines how the site connects to the Cato Cloud, such as X1500 Socket or AWS vSocket (array with nested fields)
creationTime - DateTime Timestamp for when the site was created
interfaces - [InterfaceInfo!] Basic configuration information about the Socket interface
sockets - [SocketInfo!] Data related to Socket and vSocket sites, such as serial number and Socket version (array with nested fields)
ipsec - [IPSecInfo!] data related to IPsec sites, such as IKE version
Example
{
  "name": "xyz789",
  "type": "BRANCH",
  "description": "xyz789",
  "countryCode": "abc123",
  "region": "xyz789",
  "countryName": "xyz789",
  "isHA": true,
  "connType": "SOCKET_X1500",
  "creationTime": "2007-12-03T10:15:30Z",
  "interfaces": [InterfaceInfo],
  "sockets": [SocketInfo],
  "ipsec": [IPSecInfo]
}

SiteMetrics

Fields
Field Name Description
id - ID Site ID
interfaces - [InterfaceMetrics!] Analytics that are returned for the links for a site
metrics - Metrics Traffic metrics and data for sites
Arguments
toRate - Boolean

Normalize collected metrics as per-second values

name - String Site names
info - SiteInfo Shows general information about the site (array with nested fields). Applicable only for site
hostCount - Timeseries Timeseries with the number of hosts in the site. Applicable only for site
flowCount - Timeseries Timeseries with the number of flows (connections) in the site. Applicable only for site
hostLimit - Timeseries Timeseries with the configurable limit of the number of hosts in the site. Applicable only for site
samples - Int internal use
Example
{
  "id": "4",
  "interfaces": [InterfaceMetrics],
  "metrics": Metrics,
  "name": "abc123",
  "info": SiteInfo,
  "hostCount": Timeseries,
  "flowCount": Timeseries,
  "hostLimit": Timeseries,
  "samples": 123
}

SiteSnapshot

Fields
Field Name Description
id - ID site ID
protoId - ID
connectivityStatus - ConnectivityStatus Connectivity to the Cato Cloud
haStatus - HaStatus Site HA readiness information
operationalStatus - OperationalStatus Status for a site or VPN user
lastConnected - DateTime Relevant when the site is disconnected - the last time the device was connected
connectedSince - DateTime For connected sites, since when are they connected
popName - String Name of the PoP that the site is connected to
devices - [DeviceSnapshot!] Data related to the Sockets for a site
info - SiteInfo General real-time information about the site
hostCount - Int Number of hosts connected to a site
altWanStatus - String Alternative WAN connectivity status
Example
{
  "id": "4",
  "protoId": "4",
  "connectivityStatus": "connected",
  "haStatus": HaStatus,
  "operationalStatus": "active",
  "lastConnected": "2007-12-03T10:15:30Z",
  "connectedSince": "2007-12-03T10:15:30Z",
  "popName": "xyz789",
  "devices": [DeviceSnapshot],
  "info": SiteInfo,
  "hostCount": 123,
  "altWanStatus": "abc123"
}

SiteType

Values
Enum Value Description

BRANCH

HEADQUARTERS

CLOUD_DC

DATACENTER

Example
"BRANCH"

SocketInfo

Description

Basic information about socket

Fields
Field Name Description
id - String Unique ID for Socket
serial - String Serial number for the Socket
isPrimary - Boolean For HA configurations, when this boolean value is true, this the primary Socket
platform - SocketPlatform Shows Socket type
version - String Software version number that is currently installed on the Socket
versionUpdateTime - DateTime Timestamp when the Socket upgraded to the current hardware version
Example
{
  "id": "abc123",
  "serial": "xyz789",
  "isPrimary": false,
  "platform": "X1500",
  "version": "abc123",
  "versionUpdateTime": "2007-12-03T10:15:30Z"
}

SocketInterfaceAltWanInput

Fields
Input Field Description
privateInterfaceIp - IPAddress!
privateNetwork - IPSubnet!
privateGatewayIp - IPAddress!
privateVlanTag - Int
publicInterfaceIp - IPAddress
publicNetwork - IPSubnet
publicGatewayIp - IPAddress
publicVlanTag - Int
Example
{
  "privateInterfaceIp": IPAddress,
  "privateNetwork": IPSubnet,
  "privateGatewayIp": IPAddress,
  "privateVlanTag": 123,
  "publicInterfaceIp": IPAddress,
  "publicNetwork": IPSubnet,
  "publicGatewayIp": IPAddress,
  "publicVlanTag": 123
}

SocketInterfaceBandwidthInput

Fields
Input Field Description
upstreamBandwidth - Int!
downstreamBandwidth - Int!
Example
{"upstreamBandwidth": 987, "downstreamBandwidth": 987}

SocketInterfaceDestType

Values
Enum Value Description

CATO

LAN

VRRP_AND_LAN

INTERFACE_DISABLED

ALTERNATIVE

LAYER_2_WAN

VRRP

LAN_LAG_MASTER_AND_VRRP

LAN_LAG_MASTER

LAN_LAG_MEMBER

LAN_AND_HA

Example
"CATO"

SocketInterfaceIDEnum

Description

SocketInterface available ids, INT_# stands for 1,2,3...12 supported ids

Values
Enum Value Description

LAN1

LAN2

WAN1

WAN2

USB1

USB2

INT_1

INT_2

INT_3

INT_4

INT_5

INT_6

INT_7

INT_8

INT_9

INT_10

INT_11

INT_12

WLAN

LTE

Example
"LAN1"

SocketInterfaceLagInput

Fields
Input Field Description
minLinks - Int!
Example
{"minLinks": 123}

SocketInterfaceLanInput

Fields
Input Field Description
subnet - IPSubnet!
translatedSubnet - IPSubnet
localIp - IPAddress!
Example
{
  "subnet": IPSubnet,
  "translatedSubnet": IPSubnet,
  "localIp": IPAddress
}

SocketInterfaceOffCloudInput

Fields
Input Field Description
enabled - Boolean!
publicIp - IPAddress
publicStaticPort - Int
Example
{
  "enabled": false,
  "publicIp": IPAddress,
  "publicStaticPort": 123
}

SocketInterfacePrecedenceEnum

Values
Enum Value Description

ACTIVE

PASSIVE

LAST_RESORT

Example
"ACTIVE"

SocketInterfaceRole

Values
Enum Value Description

wan_1

wan_2

wan_3

wan_4

Example
"wan_1"

SocketInterfaceVrrpInput

Fields
Input Field Description
vrrpType - VrrpType
Example
{"vrrpType": "VIA_SWITCH"}

SocketInterfaceWanInput

Fields
Input Field Description
role - SocketInterfaceRole!
precedence - SocketInterfacePrecedenceEnum!
Example
{"role": "wan_1", "precedence": "ACTIVE"}

SocketPlatform

Values
Enum Value Description

X1500

X1500_BR2

X1500B_BR2

X1600

X1700

X1700B

AWS1500

AZ1500

ESX1500

X1600_LTE

Example
"X1500"

SortInput

Fields
Input Field Description
field - String
order - DirectionInput
Example
{"field": "abc123", "order": "asc"}

String

Description

The String scalar type represents textual data, represented as UTF-8 character sequences. The String type is most often used by GraphQL to represent free-form human-readable text.

Example
"xyz789"

StringValue

Fields
Field Name Description
string - String
Example
{"string": "xyz789"}

SubDomain

Fields
Field Name Description
accountId - ID!
accountName - String!
accountType - String!
subDomain - String!
Example
{
  "accountId": "4",
  "accountName": "xyz789",
  "accountType": "xyz789",
  "subDomain": "xyz789"
}

SubnetType

Values
Enum Value Description

Routed

Direct

VLAN

Native

SecondaryNative

Example
"Routed"

TimeAnnotation

Description

An object for marking specific events in time.

Fields
Field Name Description
time - Float! Timestamp of the event
label - String! Description of the event
shortLabel - String! Brief description of the event
type - AnnotationType! Type identifies which annotation this is: e.g. connectivity, rolechange, missingdata, which allows charts to attach to it.
Example
{
  "time": 987.65,
  "label": "abc123",
  "shortLabel": "abc123",
  "type": "popChange"
}

TimeFrame

Description

Enter the time frame for the data that the query returns. The argument is in the format <type>.<time value> This argument is mandatory.

These are the supported options to define the time frame:

last.<time duration> - The

  • timeFrame = last.PT5M shows the previous 5 minutes
  • timeFrame = last.PT2H shows the previous 2 hours
  • timeFrame = last.P1D shows the previous 1 day
  • timeFrame = last.P3M shows the previous 3 months
  • timeFrame = last.P1Y shows the previous 1 year

utc.<short-time-frame-spec> - The time frame combines a start and end date in the format YY-MM-DD/hh:mm:ss
according to the specified time zone.
You must enter all the date and time values for the argument. For example:

  • timeFrame = utc.2020-02-{11/04:50:00--21/04:50:00} shows 10 days of analytics data from February 11, 2020 4:50:00 am to February 21, 2020 4:50:00 am
  • timeFrame = utc.2020-02-11/{04:50:15--16:50:15} shows 12 hours of analytics data on February 11, 2020, from 4:50:15 am to 16:50:15 pm
  • timeFrame = utc.2020-{02-11/04:50:00--04-11/04:50:00} shows 2 months of analytics data from February 11, 2020 4:50:00 am to April 11 4:50:00 am
  • timeFrame = utc.{2019-10-01/04:50:00--2020/02-01/04:50:00} shows 4 months of analytics data from October 1, 2019 4:50:00 am to February 11 4:50:00 am

This format lets you configure a time frame the includes more than one calendar year

Example
TimeFrame

TimePeriod

Description

An object for marking durations!

Fields
Field Name Description
duration - [Float!]! An tuple of two numbers representing start time, end time in ms since epoch, start bucket index, end bucket index
title - String! Label that describes the metrics
type - PeriodType! Type identifies which annotation this is: e.g. connectivity, rolechange, missingdata, which allows charts to attach to it.
Example
{
  "duration": [123.45],
  "title": "xyz789",
  "type": "packetLoss"
}

Timeseries

Fields
Field Name Description
data - [Float!] Data is an array of tuples, each containing two values: [timestamp, metric], where the timestamp is in milliseconds from the epoch (1.1.1970), and the metric is a number (according to the unit type)
Arguments
perSecond - Boolean

whether to normalize the data into per second (i.e. divide by granularity)

withMissingData - Boolean

If false, the data field will be set to '0' for buckets with no reported data. Otherwise it will be set to -1

label - String! Indicates the type of the timeseries
dimensions - [DimensionData!] List of dimension values for this timeseries
key - TimeseriesKey Timeseries key: measure and dimension values
sum - Float Summary of the metrics over the given time frame
units - UnitType Identifies what unit of data this timeseries represents. Note that toRate is only available for particular types of data to make sense.
info - [String!] Specific information about the timeseries, used to build its name, title etc
Example
{
  "data": [123.45],
  "label": "abc123",
  "dimensions": [DimensionData],
  "key": TimeseriesKey,
  "sum": 987.65,
  "units": "bytes",
  "info": ["abc123"]
}

TimeseriesKey

Fields
Field Name Description
measureFieldName - String! Measure field
dimensions - [DimensionKey!] List of dimension key-value pair for this timeseries key
Example
{
  "measureFieldName": "xyz789",
  "dimensions": [DimensionKey]
}

TimeseriesMetricType

Values
Enum Value Description

bytesUpstream

Total avg upstream traffic (from the site to the Cato Cloud)

bytesDownstream

Total avg downstream traffic (from the Cato Cloud to the site)

bytesUpstreamMax

Total max upstream traffic (from the site to the Cato Cloud)

bytesDownstreamMax

Total max downstream traffic (from the site to the Cato Cloud)

packetsUpstream

Total upstream packets

packetsDownstream

Total downstream packets

lostUpstream

Number of packets lost for upstream traffic

lostDownstream

Number of packets lost for downstream traffic

lostUpstreamPcnt

Percent of packet loss for upstream traffic

lostDownstreamPcnt

Percent of packet loss for downstream traffic

packetsDiscardedDownstream

Total packets discarded for downstream traffic

packetsDiscardedUpstream

Total packets discarded for upstream traffic

packetsDiscardedUpstreamPcnt

Percent packets discarded for upstream traffic

packetsDiscardedDownstreamPcnt

Percent packets discarded for downstream traffic

jitterUpstream

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)

bytesTotal

Total number of bytes of upstream and downstream traffic

rtt

Round-trip time from the Socket to the Cato Cloud

health

Health analytics for the site No longer supported

tunnelAge

The age of the physical tunnel in milliseconds (It is zeroed even on transparent reconnect)

lastMilePacketLoss

Packet loss from socket directly to a well known global services, not through Cato This is used to measure last mile provider's performance, independent of the service.

lastMileLatency

Latency from socket directly to a well known global service, not through Cato. This is used to measure last mile provider's performance, independent of the service.
Example
"bytesUpstream"

UnitType

Values
Enum Value Description

bytes

packets

bits

ms

percent

score

health analytics for the site

count

The number of occurrences for this unit

seconds

For metrics that are measured in seconds, such as tunnelAge, the number of seconds

bps

Bits per second

bytesPerSec

Bytes per second

none

Example
"bytes"

UpdateAccountRoleInput

Fields
Input Field Description
id - ID!
name - String
Example
{
  "id": "4",
  "name": "xyz789"
}

UpdateAdminInput

Fields
Input Field Description
firstName - String
lastName - String
passwordNeverExpires - Boolean
mfaEnabled - Boolean
managedRoles - [UpdateAdminRoleInput!]
resellerRoles - [UpdateAdminRoleInput!]
Example
{
  "firstName": "xyz789",
  "lastName": "xyz789",
  "passwordNeverExpires": true,
  "mfaEnabled": true,
  "managedRoles": [UpdateAdminRoleInput],
  "resellerRoles": [UpdateAdminRoleInput]
}

UpdateAdminPayload

Fields
Field Name Description
adminID - ID!
Example
{"adminID": "4"}

UpdateAdminRoleInput

Fields
Input Field Description
role - UpdateAccountRoleInput!
allowedEntities - [EntityInput!]
allowedAccounts - [ID!]
Example
{
  "role": UpdateAccountRoleInput,
  "allowedEntities": [EntityInput],
  "allowedAccounts": ["4"]
}

UpdateHaInput

Fields
Input Field Description
primaryManagementIp - IPAddress
secondaryManagementIp - IPAddress
vrid - Int
Example
{
  "primaryManagementIp": IPAddress,
  "secondaryManagementIp": IPAddress,
  "vrid": 987
}

UpdateHaPayload

Fields
Field Name Description
siteId - ID!
Example
{"siteId": "4"}

UpdateNetworkRangeInput

Fields
Input Field Description
name - String
rangeType - SubnetType
subnet - IPSubnet
translatedSubnet - IPSubnet
localIp - IPAddress Only relevant for NATIVE, SECONDARY_NATIVE, DIRECT_ROUTE, VLAN rangeType
gateway - IPAddress Only relevant for ROUTED_ROUTE rangeType
vlan - Int Only relevant for VLAN network rangeType
azureFloatingIp - IPAddress Only relevant for AZURE HA sites
dhcpSettings - NetworkDhcpSettingsInput Only relevant for NATIVE, VLAN rangeType
Example
{
  "name": "xyz789",
  "rangeType": "Routed",
  "subnet": IPSubnet,
  "translatedSubnet": IPSubnet,
  "localIp": IPAddress,
  "gateway": IPAddress,
  "vlan": 987,
  "azureFloatingIp": IPAddress,
  "dhcpSettings": NetworkDhcpSettingsInput
}

UpdateNetworkRangePayload

Fields
Field Name Description
networkRangeId - ID!
Example
{"networkRangeId": "4"}

UpdateSiteGeneralDetailsInput

Fields
Input Field Description
name - String
siteType - SiteType
description - String
siteLocation - UpdateSiteLocationInput
Example
{
  "name": "xyz789",
  "siteType": "BRANCH",
  "description": "abc123",
  "siteLocation": UpdateSiteLocationInput
}

UpdateSiteGeneralDetailsPayload

Fields
Field Name Description
siteId - ID!
Example
{"siteId": 4}

UpdateSiteLocationInput

Fields
Input Field Description
countryCode - String
stateCode - String
timezone - String
address - String
Example
{
  "countryCode": "xyz789",
  "stateCode": "abc123",
  "timezone": "xyz789",
  "address": "xyz789"
}

UpdateSocketInterfaceInput

Fields
Input Field Description
destType - SocketInterfaceDestType!
name - String
lan - SocketInterfaceLanInput Only relevant for LAN, VRRP_AND_LAN, LAN_LAG_MASTER, LAN_LAG_MASTER_AND_VRRP
bandwidth - SocketInterfaceBandwidthInput Only relevant for CATO, ALTERNATIVE, LAYER_2_WAN
wan - SocketInterfaceWanInput Only relevant for CATO
offCloud - SocketInterfaceOffCloudInput Only relevant for CATO
altWan - SocketInterfaceAltWanInput Only relevant for ALTERNATIVE, LAYER_2_WAN
lag - SocketInterfaceLagInput Only relevant for LAN_LAG_MASTER, LAN_LAG_MASTER_AND_VRRP
vrrp - SocketInterfaceVrrpInput Only relevant for VRRP
Example
{
  "destType": "CATO",
  "name": "xyz789",
  "lan": SocketInterfaceLanInput,
  "bandwidth": SocketInterfaceBandwidthInput,
  "wan": SocketInterfaceWanInput,
  "offCloud": SocketInterfaceOffCloudInput,
  "altWan": SocketInterfaceAltWanInput,
  "lag": SocketInterfaceLagInput,
  "vrrp": SocketInterfaceVrrpInput
}

UpdateSocketInterfacePayload

Fields
Field Name Description
siteId - ID!
socketInterfaceId - SocketInterfaceIDEnum!
Example
{"siteId": 4, "socketInterfaceId": "LAN1"}

UpdateStaticHostInput

Fields
Input Field Description
name - String
ip - IPAddress
macAddress - String
Example
{
  "name": "abc123",
  "ip": IPAddress,
  "macAddress": "abc123"
}

UpdateStaticHostPayload

Fields
Field Name Description
hostId - ID!
Example
{"hostId": 4}

UserInfo

Description

Basic User configuration information

Fields
Field Name Description
name - String Name of the VPN user
status - OperationalStatus Status of the Client as the type STRING
email - String Email address of the VPN user
creationTime - DateTime Timestamp when the VPN user was created in the account
phoneNumber - String Phone number for the VPN user
origin - String User creation mechanism, current supported REGULAR or LDAP
authMethod - String Additional authentication mechanism, currently MFA or NONE
Example
{
  "name": "xyz789",
  "status": "active",
  "email": "xyz789",
  "creationTime": "2007-12-03T10:15:30Z",
  "phoneNumber": "xyz789",
  "origin": "abc123",
  "authMethod": "xyz789"
}

UserRole

Values
Enum Value Description

OWNER

VIEWER

PUBLIC_VIEWER

PUBLIC_EDITOR

EDITOR

SUPER_USER

SITES_VIEWER

Example
"OWNER"

UserSnapshot

Fields
Field Name Description
id - ID VPN user ID
connectivityStatus - ConnectivityStatus Connectivity to the Cato Cloud
operationalStatus - OperationalStatus Status for a site or VPN user
name - String User name from configuration, same as info.name
deviceName - String The host name of the device
uptime - Int How long has the user been connected (in seconds)
lastConnected - DateTime Last time the user was connected (relevant if not currently connected)
version - String VPN client version string
versionNumber - Int VPN client version number
popID - Int ID of the PoP that the Client is connected to
popName - String Name of the PoP that the VPN user is connected to
remoteIP - String IP address of the Client
remoteIPInfo - IPInfo IP address, ISP, and geographical information related to the Client
internalIP - String IP address of the PoP that the Client is connected to
osType - String Operating system of the device the Client is running on
osVersion - String Version of the operating system for the device
devices - [DeviceSnapshot!] Data related to the Client
connectedInOffice - Boolean In this state the client does not create its own connection, but reuses the Office's socket connection
info - UserInfo General information about the VPN user
recentConnections - [RecentConnection!] Data related to the most recent completed VPN connections
Example
{
  "id": "4",
  "connectivityStatus": "connected",
  "operationalStatus": "active",
  "name": "xyz789",
  "deviceName": "xyz789",
  "uptime": 987,
  "lastConnected": "2007-12-03T10:15:30Z",
  "version": "abc123",
  "versionNumber": 987,
  "popID": 123,
  "popName": "abc123",
  "remoteIP": "abc123",
  "remoteIPInfo": IPInfo,
  "internalIP": "xyz789",
  "osType": "xyz789",
  "osVersion": "abc123",
  "devices": [DeviceSnapshot],
  "connectedInOffice": true,
  "info": UserInfo,
  "recentConnections": [RecentConnection]
}

Value

Types
Union Types

StringValue

DateValue

Entity

Example
StringValue

VrrpType

Values
Enum Value Description

VIA_SWITCH

DIRECT_LINK

Example
"VIA_SWITCH"