Reference: API Gateway examples

Use the following query examples to learn about the functionality and syntax of queries and mutations in API Gateway.

General examples

The following queries retrieve data from the endpoints in your environment.

ClosedGet server time

The following query retrieves the local time from the Tanium ServerTanium as a Service.

Copy
{
  now
}

Example response:

Copy
{
  "data": {
    "now": "2021-11-08T19:22:03Z"
  }
}

ClosedGet endpoints

The following query retrieves known endpoints from the Tanium ServerTanium as a Service.

Copy
{
  endpoints(source: {ts: {expectedCount: 1, stableWaitTime: 10}}) {
    edges {
      node {
        computerID
        name
        serialNumber
        ipAddress
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "computerID": "937672696",
            "name": "ubuntu-test",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.30"
          }
        },
        {
          "node": {
            "computerID": "1867570226",
            "name": "CentOS-test-1",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.40"
          }
        },
        {
          "node": {
            "computerID": "2711217959",
            "name": "CentOS-test-2",
            "serialNumber": "Not Specified",
            "ipAddress": "10.168.20.50"
          }
        }
      ]
    }
  }
}

ClosedGet endpoints IDs from Tanium Data Service

The following query retrieves the all endpoint IDs from Tanium Data Service.

Copy
{
  endpoints {
    edges {
      node {
        id
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345"
          }
        },
        {
          "node": {
            "id": "54321"
          }
        },
        {
          "node": {
            "id": "21212"
          }
        }
      ]
    }
  }
}

ClosedGet rich endpoint data

The following query demonstrates using nested fields to retrieve categorized endpoint data.

The first:2 argument retrieves two records; set this value higher to retrieve more records at a time. For more information on pagination arguments, see Using API Gateway.

Copy
{
  endpoints (first:2) {
    edges {
      node {
        name
        computerID
        ipAddress
        isVirtual
        chassisType
        systemUUID
        domainName
        os {
          name
          platform
          generation
        }
        processor {
          architecture
          cacheSize
          consumption
          cpu
          family
          manufacturer
          speed
        }
        lastLoggedInUser
      }
    }
    pageInfo {
      startCursor
      endCursor
      hasNextPage
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-01",
            "computerID": "1234567890",
            "ipAddress": "10.20.30.40",
            "isVirtual": false,
            "chassisType": "TSE-Error: Unknown - dmidecode unavailable",
            "systemUUID": "TSE-Error: Unknown - dmidecode unavailable",
            "domainName": "(none)",
            "os": {
              "name": "Red Hat Enterprise Linux Server release 5.11 (Tikanga)",
              "platform": "Linux",
              "generation": "Red Hat Enterprise Linux 5"
            },
            "processor": {
              "architecture": "x86_64",
              "cacheSize": "16384 KB",
              "consumption": "9.9 %",
              "cpu": "Intel Core Processor (Haswell, no TSX, IBRS)",
              "family": "6",
              "manufacturer": "GenuineIntel",
              "speed": "2600 Mhz"
            },
            "lastLoggedInUser": "reboot"
          }
        },
        {
          "node": {
            "name": "Test-02",
            "computerID": "3216549870",
            "ipAddress": "10.20.30.50",
            "isVirtual": true,
            "chassisType": "Virtual",
            "systemUUID": "[no results]",
            "domainName": "(none)",
            "os": {
              "name": "CentOS Linux release 8.4.2105",
              "platform": "Linux",
              "generation": "CentOS 8"
            },
            "processor": {
              "architecture": "x86_64",
              "cacheSize": "35840 KB",
              "consumption": "18.6 %",
              "cpu": "Intel(R) Xeon(R) CPU E5-2680 v4 @ 2.40GHz",
              "family": "6",
              "manufacturer": "GenuineIntel",
              "speed": "2400 Mhz"
            },
            "lastLoggedInUser": "tester-5"
          }
        }
      ],
      "pageInfo": {
        "startCursor": "4267468:0",
        "endCursor": "4267468:1",
        "hasNextPage": true
      }
    }
  }
}

ClosedGet a set of endpoints

The following query retrieves a set of endpoints. The query demonstrates the use of the sensorReadings field and contains a filter argument to retrieve endpoints whose names contain the letter a. The results are paginated to 3 records.

Copy
{
  endpoints(first: 3, filter: {op: MATCHES, path: "name", value: "a.*"}) {
    edges {
      node {
        name
        ipAddress
        sensorReadings(sensors: [{name: "EID Last Seen"}]) {
          columns {
            name
            values
          }
        }
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "test-1",
            "ipAddress": "10.20.20.30",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:29:28 +0000"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "test-2",
            "ipAddress": "10.20.20.250",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:29:28 +0000"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "test-3",
            "ipAddress": "10.170.10.3",
            "sensorReadings": {
              "columns": [
                {
                  "name": "EID Last Seen",
                  "values": [
                    "Mon, 08 Nov 2021 21:17:17 +0000"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedUnregistered sensor query

The following query retrieves the operating system platform from all endpoints.

In API Gateway, a sensor is unregistered if the sensor is not represented by a named field in the API Gateway schema. This has no correlation to registering sensors in Tanium Data Service.

Copy
{
  endpoints {
    edges {
      node {
        id
        name
        sensorReadings(sensors: [{name: "OS Platform"}]) {
          columns {
            name
            values
          }
        }
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "id": "12345",
            "name": "Test-01",
            "sensorReadings": {
              "columns": [
                {
                  "name": "OS Platform",
                  "values": [
                    "Linux"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "id": "54321",
            "name": "Test-03",
            "sensorReadings": {
              "columns": [
                {
                  "name": "OS Platform",
                  "values": [
                    "Linux"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedUnregistered parameterized sensor query

The following query checks to see if each endpoint contains the C:\Windows\py.exe file.

In API Gateway, a sensor is unregistered if the sensor is not represented by a named field in the API Gateway schema. This has no correlation to registering sensors in Tanium Data Service.

Copy
{
  endpoints {
    edges {
      node {
        name
        id
        sensorReadings(
          sensors: [{name: "File Exists", params: [{name: "file", value: "C:\\Windows\\py.exe"}]}]
        ) {
          columns {
            sensor {
              name
              params {
                name
                value
              }
            }
            values
          }
        }
      }
    }
  }
}

Example response:

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-01",
            "id": "12345",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "File does not exist"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "[no results]",
            "id": "54225",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "[no results]"
                  ]
                }
              ]
            }
          }
        },
        {
          "node": {
            "name": "[no results]",
            "id": "65456",
            "sensorReadings": {
              "columns": [
                {
                  "sensor": {
                    "name": "File Exists",
                    "params": [
                      {
                        "name": "file",
                        "value": "C:\\Windows\\py.exe"
                      }
                    ]
                  },
                  "values": [
                    "[no results]"
                  ]
                }
              ]
            }
          }
        }
      ]
    }
  }
}

ClosedPaginated query

The following query retrieves the first five endpoint records after the given cursor.

Copy
{
  endpoints(after: "4277520:4", first: 5) {
    edges {
      node {
        name
        id
        ipAddress
      }
    }
    pageInfo {
      hasNextPage
      startCursor
      endCursor
    }
  }
}

Example results

Copy
{
  "data": {
    "endpoints": {
      "edges": [
        {
          "node": {
            "name": "Test-06",
            "id": "6172",
            "ipAddress": "172.20.30.40"
          }
        },
        {
          "node": {
            "name": "Test-07",
            "id": "87654",
            "ipAddress": "192.168..1.80"
          }
        },
        {
          "node": {
            "name": "Test-14",
            "id": "43584",
            "ipAddress": "10.70.11.44"
          }
        },
        {
          "node": {
            "name": "Test-03",
            "id": "37233",
            "ipAddress": "[no results]"
          }
        },
        {
          "node": {
            "name": "Test-55",
            "id": "12139",
            "ipAddress": "[no results]"
          }
        }
      ],
      "pageInfo": {
        "hasNextPage": true,
        "startCursor": "4277520:5",
        "endCursor": "4277520:9"
      }
    }
  }
}

ClosedSoftware characteristics query with filter

The following query retrieves endpoints that contain software installed by Deploy, where the package ID is 1.

Copy
{
  endpoints {
    edges {
      node {
        ipAddress
        isVirtual
        domainName
        os {
          generation
        }
        lastLoggedInUser
        deployedSoftwarePackages(
          filter: {filters: [{op: EQ, path: "id", value: "1"}, {op: EQ, path: "applicability", value: "Installed"}]}
        ) {
          id
        }
      }
    }
  }
}

Action examples

ClosedCreate action (subset of endpoints)

The following mutation deploys an action to increase the verbosity of log levels on Debian endpoints.

Copy
{
  createAction(
    action: {description: "Increasing log verbosity level on all debian endpoints for troubleshooting", target: {targetGroup: "All Debian", platforms: [Linux]}, changeClientSetting: {name: LOG_VERBOSITY_LEVEL, value: "41"}}
  ) {
    id
  }
}

ClosedGet action details

The following parameterized query retrieves details and any results for an action.

Copy
query ($id: ID!) {
  lastActionDetails(id: $id) {
    id
    name
    comment
    expireSeconds
    creationTime
    startTime
    expirationTime
    distributeSeconds
    status
    stoppedFlag
  }
  lastActionResults(id: $id) {
    id
    waiting
    downloading
    running
    waitingToRetry
    completed
    expired
    failed
    pendingVerification
    verified
    failedVerification
  }
}

Include the endpoint ID in the QUERY VARIABLES panel:

Copy
{
  "id": 12323
}

Deploy examples

ClosedDeploy a package to all endpoints

The following mutation deploys a package to All Computers.

Copy
mutation {
  manageSoftware(
    operation: INSTALL
    softwarePackageID: 2
    start: "2021-10-27T00:00:00Z"
    end: "2021-11-03T00:00:00Z"
    target: {targetGroup: "All Computers"}
  ) {
    ID
    name
  }
}

ClosedGet package details

The following query retrieves multiple fields for all packages.

Copy
query PackagesQuery {
  packages {
    items {
      id
      name
      displayName
      command
      commandTimeout
      expireSeconds
      contentSet {
        id
        name
      }
      processGroupFlag
      skipLockFlag
      metadata {
        adminFlag
        name
        value
      }
      sourceHash
      sourceHashChangedFlag
      sourceID
      sourceName
      parameters {
        key
        value
      }
      rawParameterDefinition
      parameterDefinition {
        parameterType
        model
        parameters {
          model
          parameterType
          key
          label
          helpString
          defaultValue
          validationExpressions {
            model
            parameterType
            expression
            helpString
          }
          promptText
          heightInLines
          maxChars
          values
          restrict
          allowEmptyList
          minimum
          maximum
          stepSize
          snapInterval
          dropdownOptions {
            model
            parameterType
            name
            value
          }
          componentType
          startDateRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          endDateRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          startTimeRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          endTimeRestriction {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          allowDisableEnd
          defaultRangeStart {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          defaultRangeEnd {
            model
            parameterType
            type
            interval
            intervalCount
            unixTimeStamp
          }
          separatorText
        }
      }
      verifyExpireSeconds
    }
  }
}

ClosedGet Deploy packages

The following query retrieves all Deploy packages.

Copy
{
  softwarePackages {
    edges {
      node {
        id
        productName
        productVendor
        productVersion
      }
    }
  }
}

ClosedGet software deployment status

The following query retrieves the deployment status of all Deploy packages.

Copy
{
  softwareDeployment {
    ID
    name
    status {
      completeCount
      downloadCompleteWaitingCount
      downloadingCount
      failedCount
      notApplicableCount
      runningCount
      waitingCount
    }
    errors {
      error
      count
    }
  }
}

Direct Connect examples

The following queries and mutations use Direct Connect to connect to a single endpoint, retrieve data, stop a process, and then close the connection.

ClosedOpen a connection to an endpoint

The following mutation uses Direct Connect to establish a connection to the endpoint with an ID of 12323. You can retrieve IDs through the Get endpoints IDs from Tanium Data Service query.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation {
  openDirectConnection(input: {endpointID: "12323"}) {
    connectionID
  }
}

Example response:

Copy
{
  "data": {
    "openDirectConnection": {
      "connectionID": "86d9a9ac-0229-481b-9d88-5f1bcb1b177b"
    }
  }
}

ClosedPing the connection to an endpoint

The following mutation retrieves the status for a Direct Connect connection. Use this mutation to check connection details or to keep the connection active. You need the connectionID that is returned by the mutation to open the connection.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation ($connectionID: ID!) {
  pingDirectConnection(input: {connectionID: $connectionID}) {
    result
  }
}

Include the connection ID in the QUERY VARIABLES panel:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

ClosedGet data from an endpoint

After you establish a connection to an endpoint through Direct Connect, you can query the endpoint for specific information. You need the connectionID that is returned by the mutation to open the connection. The following query retrieves the CPU usage on the endpoint:

Copy
{
  directConnection(connectionID: "7212763a-20aa-4cdd-a8b2-6b20b3968f2a") {
    performance {
      cpuUsagePercent
    }
  }
}

ClosedGet process from an endpoint

The following query retrieves the state of the winit.exe process on the endpoint, if it exists. You need the connectionID that is returned by the mutation to open the connection.

Copy
query ($connectionID: ID!) {
  directConnection(connectionID: $connectionID) {
    processes(name: "winit.exe") {
      all {
        pid
        ppid
        name
        commandLine
        userName
        groupName
        memoryResidentBytes
      }
    }
  }
}

Include the connection ID in the QUERY VARIABLES panel:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

ClosedGet alerts from an endpoint

The following query retrieves alerts from an endpoint. You need the connectionID that is returned by the mutation to open the connection.

Copy
query ($connectionID: ID!) {
  directConnection(connectionID: $connectionID) {
    alerts {
      all {
        schema
        key
        type
        ref
        topProcessesExpr
        labels
        pendingAt
        start
        resolvedAt
        leadup
        value {
          name
          value
          values {
            value
            labels
          }
        }
      }
    }
  }
}

Include the connection ID in the QUERY VARIABLES panel:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

ClosedStop a process on an endpoint

The following mutation stops a process named foo on an endpoint. You need the connectionID that is returned by the mutation to open the connection.

Copy
mutation {
  killProcess(
    input: {connectionID: "7212763a-20aa-4cdd-a8b2-6b20b3968f2a", name: "foo", pid: 1, signal: SIGKILL}
  ) {
    result
  }
}

ClosedClose connection to an endpoint

The following mutation closes a Direct Connect connection to an endpoint. You need the connectionID that is returned by the mutation to open the connection.

Direct Connect connections close after two minutes of inactivity.

Copy
mutation ($connectionID: ID!) {
  closeDirectConnection(input: {connectionID: $connectionID}) {
    result
  }
}

Include the connection ID in the QUERY VARIABLES panel:

Copy
{
  "connectionID": "5fc564d6-5767-47fc-abb6-25cba65409d8"
}

Example response:

Copy
{
  "data": {
    "closeDirectConnection": {
      "result": true
    }
  }
}