Pagination

The GraphQL API supports cursor-based pagination following the GraphQL Connections specification. This allows you to retrieve large sets of data efficiently by requesting a limited number of results per query and fetching additional pages as needed.

Use Pagination Parameters

To paginate through results, use the first and after arguments:

• first: {number} – Specifies the number of results to return in the request.
• after: {cursor} – Specifies the cursor to retrieve the next page of results.

📘

Note

This is a standard way of using pagination in GraphQL. For more information see GraphQL pagination.

Example Query - Fetch First 5 Items

The following query uses the first field to fetch the first 5 items from a list of virtual machines.

query {
  VirtualMachines(first: 5, filter: {VulnerabilitySeverities: [Critical, High]}) {
    totalCount
    pageInfo {
      hasNextPage
      endCursor
    }
    edges {
      node {
        Name
        Vulnerabilities {
          Id
          Severity
          Description
        }
        ResolvedVulnerabilities {
          Id
          Severity
          ResolutionTime
        }
      }
    }
  }
}

Fetch the Next Page

To retrieve additional results, first make an initial query.

• For the initial query, use null as the value for `after'
• If pageInfo.hasNextPage is true in the response, use pageInfo.endCursor as the after value in the next request to retrieve the next set of results.

Example Queries - Fetch Next Page

The following queries show how to fetch the next page.

Step 1: Initial Query

query {
  Findings(first: 10, after: null){
    nodes {
      Policy {
        Description
        Name
        ScopeId
      }
      Status
      CreationTime
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sample Response

{
  "data": {
    "Findings": {
      "nodes": [
        {
          "PolicyName": "Inactive IAM role",
          "Status": "Open",
          "CreationTime": "2024-08-13T00:49:10.532Z"
        },
        ...
      ],
      "pageInfo": {
        "hasNextPage": true,
        "endCursor": "cursor10"
      }
    }
  }
}

Since pageInfo.hasNextPage is true, we can fetch the next page using pageInfo.endCursor (cursor10).

Step 2: Fetching the Next Page

Now, use after: "cursor10" to get the next set of results:

query {
  Findings(first: 10, after: "cursor10"){
    nodes {
      Policy {
        Name
      }
      Status
      CreationTime
    }
    pageInfo {
      hasNextPage
      endCursor
    }
  }
}

Sample Response

{
  "data": {
    "Findings": {
      "nodes": [
        {
      "Policy": {
            "Name": "Virtual Machine has vulnerabilities that should be addressed"
          },
          "Status": "Open",
          "CreationTime": "2024-09-14T00:43:10.578Z"
        },
        ...
      ],
      "pageInfo": {
        "hasNextPage": false,
        "endCursor": "cursor20"
      }
    }
  }
}

• If pageInfo.hasNextPage is now false, all results have been retrieved.
• Otherwise, continue paginating using the latest endCursor.

Handling Pagination Efficiently

• Always check pageInfo.hasNextPage to determine if more data is available.
• Avoid fetching excessively large page sizes, as this may impact performance.
• Store and reuse cursors when necessary to navigate pages efficiently.