Pagination

GraphQL Pagination

GraphQL queries may provide access to large lists of data. For performance reasons, fields referring to lists of non-fixed size require pagination to show a user-defined subset of data per request.

Vanta's pagination follows the Relay Pagination Spec. We recommend you familiarize yourself with this reference alongside our Explorer doc.

🚧
Attention!
Vanta's paginated fields are capped at 100 items per page.

You'll encounter the error below if you attempt to query more than 100 items:

"errors": [
    {
      "message": "Invalid argument value",
        "detail": "Too many items requested. Maximum: 100",
        "code": "BAD_USER_INPUT"
      }
    }
  ],
  "data": null
}

Pagination Arguments

$first: Int | $last: Int

Either first or last must be provided when querying a paginated field, to specify how many items to return.

For example, we can set first: 2 in the AsanaTaskList query to get only the first 2 Asana tasks:

query ExampleQuery($first: Int) {
  organization {
    AsanaTaskList(first:2) {
      edges {
        node {
          displayName
          priority
        }
      }
    }
  }
}

{
  "data": {
    "organization": {
      "AsanaTaskList": {
        "edges": [
          {
            "node": {
              "displayName": "[Vanta] Remediate \"General security awareness training records tracked\"",
              "priority": null
            }
          },
          {
            "node": {
              "displayName": "new security task 3",
              "priority": null
            }
          }
        ]
      }
    }
  }
}

To see how many Asana Tasks we have total, we can use the totalCount field:

query ExampleQuery($first: Int) {
  organization {
    AsanaTaskList(first:2) {
      totalCount 
      edges {
        node {
          displayName
          priority
        }
      }
    }
  }
}

{
  "data": {
    "organization": {
      "AsanaTaskList": {
        "totalCount": 17,
        "edges": [
          {
            "node": {
              "displayName": "[Vanta] Remediate \"General security awareness training records tracked\"",
              "priority": null
            }
          },
          {
            "node": {
              "displayName": "new security task 3",
              "priority": null
            }
          }
        ]
      }
    }
  }
}

Cursors

A cursor is a unique String value that references a specific item (node) in the results. You can obtain cursors for each item on the page by selecting the cursor field in edges.

To get the first or last cursor of the current page, you can query startCursor and endCursor within the pageInfo field. hasNextPage and hasPreviousPage indicate whether there is more data after the end cursor or before the start cursor, respectively.

query ExampleQuery{
  organization {
    AsanaTaskList(first:2) {
      pageInfo {
        endCursor
        startCursor
        hasNextPage
        hasPreviousPage
      }
      edges {
        node {
          createdAt
          displayName
        }
        cursor
      }
    }
  }
}

{
  "data": {
    "organization": {
      "AsanaTaskList": {
        "pageInfo": {
          "endCursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZTEy",
          "startCursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZGVl",
          "hasNextPage": true,
          "hasPreviousPage": false
        },
        "edges": [
          {
            "node": {
              "createdAt": "2022-03-04T22:19:54.864Z",
              "displayName": "[Vanta] Remediate \"General security awareness training records tracked\""
            },
            "cursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZGVl"
          },
          {
            "node": {
              "createdAt": "2022-03-04T22:19:54.868Z",
              "displayName": "new security task 3"
            },
            "cursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZTEy"
          }
        ]
      }
    }
  }
}

$after:String | $before:String

after and before use cursors to specify the position in the array from which to request data.

after is used with first to paginate in a "forward manner". The API will return data after the cursor specified through after.

query Organization($after:String) {
  organization {
    AsanaTaskList(first:2, after: "NjIyMjkwOGExYTljY2E2NWRmZjhmZTEy") {
      pageInfo {
        endCursor
      }
      edges {
        cursor
        node {
          displayName
        }
      }
    }
  }
}

{
  "data": {
    "organization": {
      "AsanaTaskList": {
        "pageInfo": {
          "endCursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZTRl"
        },
        "edges": [
          {
            "cursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZTI2",
            "node": {
              "displayName": "another lowercase security task"
            }
          },
          {
            "cursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZTRl",
            "node": {
              "displayName": "A security task"
            }
          }
        ]
      }
    }
  }
}

before is used with last to paginate in a "backward manner". The API will return data before the cursor specified in before.

query Organization($before:String) {
  organization {
		AsanaTaskList(last:2, before: "NjIyMjkwOGExYTljY2E2NWRmZjhmZTEy") {
      pageInfo {
        endCursor
      }
      edges {
        cursor
        node {
          displayName
        }
      }
    }
  }
}

{
  "data": {
    "organization": {
      "AsanaTaskList": {
        "pageInfo": {
          "endCursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZGVl"
        },
        "edges": [
          {
            "cursor": "NjIyMjkwOGExYTljY2E2NWRmZjhmZGVl",
            "node": {
              "displayName": "[Vanta] Remediate \"General security awareness training records tracked\""
            }
          }
        ]
      }
    }
  }
}

A forward-facing argument like first and a backward-facing argument like before may not be used together.

For example, if we query AsanaTaskList(first:10, before: "NjIyMjkwOGExYTljY2E2NWRmZjhmZTEy"), we get:

{
  "errors": [
    {
      "message": "Invalid argument value",
      "extensions": {
        "invalidFields": [
          "first",
          "last",
          "before"
        ],
        "detail": "Cannot specify 'first' with backward pagination arguments",
        "code": "BAD_USER_INPUT"
      }
    }
  ],
  "data": null
}

GraphQL Pagination

🚧Attention!

Pagination Arguments

$first: Int | $last: Int

Cursors

$after:String | $before:String

🚧
Attention!