This document outlines the API v2 reporting endpoints for Reports. This version includes asynchronous endpoints for handling large datasets, increased data limits, and more intuitive, RESTful URL structures.
The following are key features:
- Asynchronous Endpoints: endpoints allow for initiating a query for a large report/widget, polling for its status, and retrieving the results once complete.
- Increased Data Limit Parameter: the limit query parameter allows users to retrieve a custom number of rows (default 5000 (5K), maximum 10000 (10K)).
- Report & Widget Filtering: filter the list of reports or widgets using a partial-match reportName or widgetName query parameter.
- RESTful URL Convention: endpoints are intuitive, using path parameters (e.g., /reports/{reportId}/widgets/{widgetId}) instead of query parameters for IDs.
More information about this REST API is available in Swagger. In the UI, navigate to Settings > Tools > REST API v2 and click API Documentation to access the Swagger API documentation. To learn more about REST APIs, see REST API v2 Overview.
Authentication and Authorization
API v2 supports the following token types:
Personal User Token
- Generation: Generated from the user’s profile menu in the Netskope UI.
- Scope: This token is tied directly to the user who generated it. All API calls made with this token will run as that user, respecting all their permissions and only returning data they can see (including their personal reports).
Service Account Token
- Generation: Generated from the RBAC menu in the Netskope UI.
- Scope: The service account is tied to a role, not to a specific user.
- Consideration: There will be no personal dashboards or widgets for this type of account since it is not tied to a user. Users can only access common or shared dashboards and widgets.
API Endpoint Details
The following endpoints are a subset of the complete list for Reports. To view details for all GET and POST endpoints and examples, navigate to Settings > Tools > REST API v2 > API Documentation to access the Swagger API documentation. Scroll down the list to the Reporting section.
Synchronous Endpoints (For Standard Queries)
These endpoints are for standard, quick-running queries.
- List All Reports
- Endpoint: GET /api/v2/reporting/er/reports
- Description: Fetches all user’s accessible reports with optional filtering by report name. The search will checl if a report name contains the given name. In addition, there’s an optional reportName query parameter for partial-match filtering (e.g., ?reportName=ciso).
- Get Widget Data (Synchronous)
- Endpoint: GET /api/v2/reporting/er/reports/{reportid}/widgets
- Description: Retrieves the data for a specific report.
- Other Parameters: resultFormat (e.g. json).
Asynchronous Endpoints (For Large Data Queries)
This is a 3-step workflow designed to prevent API timeouts when fetching large datasets.
Step 1: Create Asynchronous Task
- Endpoint: POST /api/v2/reporting/er/reports/{reportId}/widgets/{widgetId}/async
- Description: Initiates an asynchronous query for a specific widget. This call also accepts the limit and resultFormat parameters.
- Successful Response: Returns a query_task_id.
{
"query_task_id": "a1b2c3d4-..."
}
Step 2: Check Task Status
- Endpoint: GET /api/v2/reporting/er/tasks/{taskId}/status
- Description: Poll this endpoint using the query_task_id from Step 1 to check the job’s status.
- Successful Response: Returns the status. You should poll until the status is “complete”.
{
"status": "complete",
"dashboard_id": "333",
"widget_id": "363",
"result_format": "csv",
"runtime": 1.5,
"source": "async_api"
}
Step 3: Retrieve Task Result
- Endpoint: GET /api/v2/reporting/er/tasks/{taskId}/result
- Description: Once the status is “complete,” call this endpoint to retrieve the final data payload (in JSON or CSV format).
Considerations
- No Pagination: the API does not support pagination (i.e., using “page” or “offset” parameters). The only method to control data volume is by using the limit parameter.