Reference: Paginated query syntax

Query pagination allows you to retrieve a portion of a records collection (a page) per query response, preserving system performance but enabling full record retrieval through multiple responses. You can adjust the number of records returned per page, and retrieve different pages in the collection.

For the best results, due to the variability in size of Tanium deployments, retrieve 100 records per page as an initial test of your paginated query, and adjust the number of records returned per page based on performance and response time.

When you submit a paginated query request, the API Gateway service assigns an opaque string that is valid for that query and collection (a cursor) to each record in the collection. Cursors generally persist for five minutes after the most recent use of any cursor in that collection.

For example, endpoints queries support pagination. If you submit an endpoints query request and receive a cursor in the response:

  • You can reference this cursor in a successive query of that records collection to retrieve pages of records before or after a given cursor. You can repeat this process to retrieve all pages in the collection.

  • You cannot reference this endpoints-associated cursor in a sensors query. The cursor is valid only for the endpoints collection.

  • If you wait more than five minutes, then submit another endpoints query request referencing a cursor from the initial query request, the response returns an error because the cursors associated with your initial query are no longer valid.

Paginated queries generally support the following syntax:

  • <field>.edges - retrieve information about a record in the collection

  • <field>.pageInfo and <field>.totalRecords - retrieve information about pages and cursors in the collection, and collection total size

  • <field> (arguments) syntax to configure the number of records returned, and a cursor in the collection to determine which records to retrieve

A field might not support all of these fields and arguments. For more information on specific fields, see the Documentation Explorer.

Edges

Fields that support query pagination define an edge as a record within the collection. For each edge, you can retrieve the following fields:

  • <field>.edges.node - specific information about the object in that record

  • <field>.edges.cursor - the record cursor

ClosedEdge query syntax

Use the following syntax to retrieve records for a field that supports query pagination:

query {
  <field> {
    edges {
      node {
        <record-field-1>
        <record-field-2>
        <record-field-n>
      }
      cursor
    }
  }
}

For example, the following query retrieves endpoint edges; for each edge, the response returns the endpoint name and IP address, and the cursor associated with that edge. The request does not specify pagination arguments, so the response by default returns the first 20 records from the collection.

Copy
query endpointsQuery {
  endpoints {
    edges {
      node {
        name
        ipAddress
      }
      cursor
    }
  }
}

Page information

Fields that support query pagination allow you to retrieve information about a page of records in the collection using the following fields:

  • <field>.pageInfo.endCursor - the last cursor in the current page

  • <field>.pageInfo.hasNextPage - whether there are pages after the current page in the collection

Fields that support query pagination might also support the following fields:

  • <field>.pageInfo.hasPreviousPage - whether there are pages before the current page in the collection

  • <field>.pageInfo.startCursor - the first cursor in the current page

  • <field>.totalRecords - the total number of records in the collection

ClosedPage information query syntax

Use the following syntax to retrieve page information for a field that supports query pagination:

query {
  <field> {
    edges {
      node {
        <record-field-1>
        <record-field-2>
        <record-field-n>
      }
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
  }
}

For example, the following query retrieves endpoints and also returns page information, including the first cursor, last cursor, and whether there are pages before and after the current page in the collection. The query also returns the total number of records in the collection. The request does not specify pagination arguments, so the response by default returns the first 20 records from the collection.

Copy
query endpointsQueryPageInfo {
  endpoints {
    edges {
      node {
        name
        ipAddress
      }
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
  }
}

Paginated collection traversal arguments

Fields that support query pagination have arguments that control the number of records returned per page and which page is returned. If a query does not specify these arguments, the default settings generally return 20 records forward from the first page at the start of the collection.

Use the following arguments to traverse forward in a records collection:

  • <field> (after) - retrieve records after the specified cursor

  • <field> (first) - retrieve the first number of records after a cursor, or at the beginning of the collection if no cursor is specified

Use the following arguments to traverse backward in a records collection:

  • <field> (before) - retrieve records before the specified cursor

  • <field> (last) - retrieve the last number of records before a cursor

In a single query request, you can retrieve results either forward from a cursor or backwards from a cursor. You cannot specify both before and after in a single query request.

ClosedForward traversal argument syntax

Use the following syntax to retrieve the first number of results from the start of a paginated records collection:

<field>(first: <Int>)

Use the following syntax to retrieve the first number of results without specifying a cursor (null), such as when you first retrieve records and pages from a paginated records collection:

<field>(after: null, first: <Int>)

Use the following syntax to retrieve the first number of results after a specified cursor in a paginated records collection, such as when you retrieve <field>.pageInfo.endCursor in a prior query and want to traverse forward to retrieve the next page of records:

<field>(after: <Cursor>, first: <Int>)

For example, the following query retrieves the first 20 endpoint records from the beginning of the collection, and also returns cursor information for this first page, including endpoints.pageInfo.endCursor for the last cursor on the page:

Copy
query endpointsQueryNullCursor {
  endpoints (after: null, first: 20){
    edges {
      node {
        name
        ipAddress
      }
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
  }
}

To retrieve the next page of 20 records in this collection, pass the endpoints.pageInfo.endCursor value from the prior query as the after argument value:

Copy
query endpointsQueryNextPage {
  endpoints (after: <endpoints.pageInfo.endCursor-value>, first: 20){
    edges {
      node {
        name
        ipAddress
      }
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
  }
}

Continue submitting requests with the endpoints.pageInfo.endCursor value from the prior query response to retrieve successive pages in the collection. If a response includes endpoints.pageInfo.hasNextPage equals false, you retrieved the last page in the collection.

ClosedBackward traversal argument syntax

Use the following syntax to retrieve the prior number of results before a specified cursor in a paginated records collection, such as when you retrieve <field>.pageInfo.startCursor in the prior query and want to traverse backward to retrieve the prior page of records:

<field>(last: <Int>, before: <Cursor>)

For example, if you retrieve the endpoints.pageInfo.startCursor value from a query and endpoints.pageInfo.hasPreviousPage equals true, a page of results precedes the page in the response. To retrieve the prior page of 20 records in this collection, pass the endpoints.pageInfo.startCursor value from the prior query as the before argument value:

Copy
query endpointsQueryPreviousPage {
  endpoints (before: <endpoints.pageInfo.startCursor-value>, last: 20){
    edges {
      node {
        name
        ipAddress
      }
      cursor
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
  }
}

Continue submitting requests with the endpoints.pageInfo.startCursor value from the prior query response to retrieve prior pages in the collection. If a response includes endpoints.pageInfo.hasPreviousPage equals false, you retrieved the first page in the collection.

Paginated endpoints collection refresh argument

If you want to obtain updated information from an endpoints collection, such as if you expect endpoints to respond several minutes after your initial query request, you can refresh the collection. If your query request refreshes the collection, the API Gateway service updates collection results with current information, invalidates the prior set of cursors, and assigns new cursors to the records. The endpoints.collectionInfo field returns additional information about endpoints in the collection, including information about endpoints that responded to the query, and an endpoints.collectionInfo.startCursor cursor value. This value always points to the first cursor in the collection; you can reference this cursor value to refresh a collection.

Use the endpoints (refresh) argument to refresh an endpoints collection and the associated cursors.

ClosedCollection and cursor refresh argument syntax

Use the following syntax to refresh a paginated endpoint records collection and the associated cursors, such as when you expect the set of endpoints to update after your initial query, and you retrieved endpoints.collectionInfo.startCursor in a prior query:

endpoints (refresh: <Cursor>)

The following example returns the startCursor value and additional endpoint information:

Copy
query endpointsQueryCollectionInfo {
  endpoints {
    edges {
      node {
        name
        id 
      }
      cursor 
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
    collectionInfo {
      active
      contributedTotal
      expectedTotal
      respondedPercentage
      respondedTotal
      startCursor
      success
    }
  }
}

After you obtain the endpoints.collectionInfo.startCursor value, and more endpoints respond to the query, you can refresh the collection of endpoints by passing endpoints.collectionInfo.startCursor as the refresh argument value:

Copy
query endpointsQueryRefresh {
  endpoints (refresh: <endpoints.collectionInfo.startCursor-value>{
    edges {
      node {
        name
        id 
      }
      cursor 
    }
    pageInfo {
      startCursor
      endCursor
      hasPreviousPage
      hasNextPage
    }
    totalRecords
    collectionInfo {
      active
      contributedTotal
      expectedTotal
      respondedPercentage
      respondedTotal
      startCursor
      success
    }
  }
}

Because the collection refresh also refreshes the collection's cursors, you must pass updated cursors the next time you want to query this updated collection.