Netskope Global Technical Success (GTS)

How to Query Netskope Client Status Using REST API v2

Netskope Cloud Version - 122

Objective

This document contains instructions for customers who wish to query Netskope Client status via Netkope Rest API v2.

Parent Article

Link

Context

The Netskope Client periodically reports Client status to the Netskope backend to have visibility in the  tenant UI for different aspects of Clients. For example, status about user-initiated actions (enable/disable), installation/upgrade status, current tunnel status (Up/Down) etc. Users can check the Client status logs on the device page on the tenant UI.

Through the use of a Client status iterator, the Netskope platform tracks log consumption though a simplified operational workflow. When a consumer requests a page of Client status events from the endpoint, Netskope delivers the requested events, and writes an index with the watermark of events provided. When the consumer has completed processing the requested page of events, the consumer simply requests the next page.

IMPORTANT

As opposed to Client Data (endpoint in Rest API v1: api/v1/clients), the iterator will only capture Client Status post its creation, not before.

Example #1:

1. The device page reports data in the last 7 days.
2. We created the iterator today at 13:00.
3. No new client events have been inserted within the Device Page post the creation of the iterator.
4. When querying Iterator, the response body will be empty.

Example #2:

1. The device page reports data in the last 7 days.
2. We created the iterator today at 13:00.
3. New client events have been inserted within the Device page post the creation of the iterator.
4. When querying Iterator, the response will contain the client status.

Workflow

Step 1

Path: Netskope Tenant UI >>> Settings >>> Tools >>> Rest API v2, and ensure that Rest API v2 is enabled.

Step 2

Click on “New Token”, enter a token name, edit the expiration time, click on “add endpoint”, search by iterator, grant read and write access, save and copy the token.

Step 3

Click on “API Documentation” to open Swagger page.

Step 4

Once Swagger is open, click on “Authorize” then add the token given above.

Step 5

Once the token is authorized, scroll down to find “/api/v2/events/dataexport/iterator/{name} Create a new iterator”, then click on “try it out”, then add a name and click on “Execute”

Note: Copy the iterator name given within the response body, for this example is:

MyFirstiterator_3489518e-2b97-4828-b60b-20db98723b7a

Step 6

Once we created an iterator, we need to ensure that is ready to be used, for this, now use: "/api/v2/events/dataexport/iterator/{name} Get iterator status", click on “try this out”, and enter the above iterator name, then click on “Execute”

Step 7

Once our iterator is ready, we can pull client events generated and inserted on the Devices page from that moment and on.

Look for

"/api/v2/events/dataexport/iterator/{name}/events Export events generated by Netskope", then click on “try it out”, enter your iterator name, then click on “Execute”

Highlights

• Response body contains the client data in a .csv format, which by clicking “download” will be shown as below

• Review the wait_time attribute in the response header and wait for enough time accordingly, like “wait_time”: 1

API Limits

• We allow only one Client status iterator per tenant.
• Concurrent Create Iterator or Delete Iterator requests are not supported and could result in a request failure.
• The iterator service is designed to stream the recent event logs with high speed. You can only request for event logs that are not older than a certain time period; older events are dropped automatically if not requested in time. The supported retention for Client status iterators is 7 days.
• Concurrent event fetch requests on the same iterator are not supported and will result in request failure.
• Multiple consumers request event logs from the same iterator concurrently is not supported and could result in the appearance of missing data on the consumer.

Terms & Condition

• All documented information undergoes testing and verification to ensure accuracy.
• In the future, If any such platform changes are brought to our attention, we will promptly update the documentation to reflect them.

Notes

• This article is authored by Netskope Global Technical Success (GTS).
• For any further inquiries related to this article, please contact Netskope GTS by submitting a support case with 'Case Type – How To Questions'.