NQL

The NQL API allows you to extract data from the Nexthink cloud platform, giving you the flexibility to create and visualize metrics using external applications.

Setting up API credentials

To set up an integration using the Nexthink API, you must first create a set of dedicated credentials in your instance for your application or service. Refer to the API Credentials documentation.

Permissions

To enable proper permissions for NQL API queries:

1. Select Administration from the main menu.

2. Click on Profile from the navigation panel.

3. Click on the New Profile button to create a new profile or edit an existing profile by hovering over it and clicking on the edit icon to change the profile configuration.

4. In the Permissions section, scroll down to the Administration section and select Manage all NQL API queries to enable appropriate permissions for the profile.

Refer to the Profiles documentation for a detailed description of the permission options.

Preparing queries

The NQL API executes predefined queries using the Nexthink web interface. Each query gets a unique ID, a required parameter for every API call.

Accessing NQL API queries

1. Log in to the Nexthink web interface.

2. Select Administration from the main menu.

3. Click on NQL API queries in the navigation panel in the Content Management section.

Managing NQL API queries

1. Create a new NQL API query by clicking on the New NQL API query button in the top-right corner of the page.

2. Edit an existing query by hovering over it to reveal the action menu on the right side, click on it and select the Edit option.

3. Use the Delete option from the action menu to permanently delete a saved query.

Configuring an NQL API query

• Name: Enter the name as you would like it to appear on the list of queries.

• Query ID: Enter an identifier for the query. Once you have created the query, you can no longer change the Query ID.

• Description (optional): Enter a description to help others understand the meaning and purpose of the query.

• NQL query: Write the NQL query to execute. Refer to the NQL documentation for more information.

Parameterized NQL queries

Parameterized NQL queries allow you to place parameters on a query instead of including a constant value. The system uses placeholders for parameters and provides the parameter value during execution. This approach allows you to reuse the query with different values for different purposes. For example, use a parameterized query to get the number of hard resets on a device, with a different device each time. With this generalized approach, you don’t need to write a separate query for each device.

Create a parameterized query:

1. Create a new NQL API query or edit an existing one.

2. Write an NQL query and explicitly name the parameters in the where clause. Parameters are allowed only in the where clause.

3. The parameter name must begin with a single $ character and must be unique within the scope of the query.

4. The parameter datatype is inferred upon query execution.

execution.crashes during past 240h
| where device.collector.uid == $collector_uid
| summarize c1 = number_of_crashes.sum()

In the example above, $collector_uid is the placeholder for a Collector UID. Provide the UID value upon query execution.

Choosing the right endpoint

The NQL API provides two separate endpoints to start the execution of a query:

• api/v2/nql/execute - highly optimized for relatively small requests at a high frequency.

• api/v1/nql/export - optimized for large queries at a low frequency.

The execute operation returns the results immediately in the response, however the export operation, since it is a longer and heavier operation, returns an identifier whose status you can consult at the following endpoint:

• api/v1/nql/status/{exportId} - Retrieves the status of an export and the URL link to a file containing the results once the execution is COMPLETE. For security, the URL link is only valid and accessible for 15 minutes after generation.

Suggested example use cases for each endpoint:

Both endpoints support the execution of the same NQL queries. However, the limits that apply to each NQL API endpoint are different. See the Limitations section below.

Output formats

The execute operation supports both CSV and JSON formats.

The status endpoint associated with the export operation provides a URL to download a CSV file that contains the actual result of the NQL query.

Limits

Nexthink makes continuous improvements to NQL to ensure optimal performance of all requests. Refer to the Nexthink Infinity thresholds and limits overview for the list of the most up-to-date limits.

Nexthink aims to maintain optimal service performance. In the case of excessive and rapid acceleration of API use, Nexthink may temporarily pause access to the NQL API on a per-tenant basis.

Supported compression algorithms

NQL Analytical API exports now support file compression using the GZIP and ZSTD algorithms, enabling faster downloads and smaller file sizes.

Reduce throttling errors

Consider the following best practices to avoid throttling:

Targeted queries

Use filters to target your query to only the data you need. For example, if you want information about a specific device, use the where clause to restrict the returned data to only that device.

Catch errors caused by rate limiting

When throttling occurs, the API returns the HTTP status code 429, and the requests fail. It is best practice to catch 429 responses in your code and retry the request after a suitable waiting period. Refer to the value specified in the Retry-After header from the response.

Reducing the number of API requests

Optimize your code to eliminate any unnecessary API calls and cache frequently used data.

Regulate the request rate

If you regularly approach or bump into the rate limit, consider including a process in your code that regulates the rate of your requests so that they are more evenly distributed over time.

Example

A set of utilities for different programming languages is available to integrate with execute and export operations. Below is an example of how to use PowerShell scripts and Power BI queries.

PowerShell

A collection of scripts compatible with PowerShell 7.2 (LTS) is available. These scripts enable customization of authentication credentials, NQL queries, parameters, output directory, file name, and format, as outlined in the output formats section.

• Execute NQL queries: PowerShell script for execute operation

• Export NQL query results: PowerShell script for export operation

Power BI

Nexthink offers two Power BI connectors as examples for connecting to the NQL API. These connectors allow the customization of authentication credentials, NQL queries, and parameters.

To start integration with NQL API, follow these steps:

• Install the custom connector from Power BI Desktop. Refer to the Microsoft Power BI documentation for detailed installation instructions.

• Open Power BI Desktop and click on Get Data in the toolbar.

• Type Nexthink in the search field to select the desired custom connector from the results.

• Click the Connect button. The configuration tab appears.

• Enter the necessary data and then click the OK buttom.

Use custom connectors to:

• Execute NQL queries: Power BI query custom connector for execute operation

• Export NQL results: Power BI query custom connector for export operation