Pagination

Using page tokens to navigate subsets of results.

Many Veza endpoints return pages of results by default, or are paginated when setting the page_size query parameter.

When making API requests that return multiple items, the response will include the following pagination-related fields:

• has_more: A boolean indicating whether there are additional results available

• next_page_token: A token that can be used to retrieve the next page of results

To get the next page of results, use the value returned by next_page_token to set the page_token query parameter for the next page of results.

When implementing pagination, you must rely on the has_more field to determine if there are additional results available. Veza APIs may return a non-empty next_page_token even when there are no more results available.

• Set the maximum number of results per page and the page to begin returning results with page_size (maximum 100) and page_token: POST /api/v1/assessments/query_spec:nodes?page_size=10&page_token=Na%3D%3D

• Responses with more than one page will contain "has_more": "true" and include the next_page_token string.

• A page can be empty even when more results exist. Always check the has_more field in the response to verify if additional results exist.

• The page_token query parameter must be URL-encoded in POST requests (replacing non-alphanumeric characters). You can achieve this with the urllib.parse.urlencode python function or another utility.

Sample Request

POST "/api/v1/assessments/query_spec:nodes?page_size=1&page_token=Na%3D%3D" \
{
  "query_type": "DESTINATION_NODES",
  "include_nodes": true,
  "source_node_types": {
    "nodes": [
      {
        "node_type": "S3Bucket",
        "node_id": "arn:aws:s3:::cct-ctr01a-terraform-baker"
      }
    ]
  },
  "destination_node_types": {
    "nodes": [
      {
        "node_type": "AwsIamUser"
      }
    ]
  },
  "no_relation": false,
  "canonical_permissions": {}
}

Sample response

{
  "values": [
    {
      "id": "arn:aws:iam::123456789012:user/AssumeCtr01Su",
      "type": "AwsIamUser",
      "properties": {
        "aws_account_id": "123456789012",
        "created_at": "2021-03-02T00:33:03Z",
        "full_admin": false,
        "last_used_at": "1970-01-01T00:00:00Z",
        "name": "AssumeCtr01Su",
        "permission_boundary_controlled": false,
        "programmatic_access_count": 1,
        "root": false,
        "user_type": ""
      },
      "destination_node_count": 0,
      "permissions": []
    }
  ],
  "next_page_token": "MQ==",
  "has_more": true
}