Real-Time API

Nexalis Cloud exposes a powerful real-time API which allows users to query and fetch high-frequency sensor data using WarpScript, a stack-based language designed for time-series analysis.

Quick Start Examples

Nexalis Macros - Learn how to use Nexalis custom macros for simplified queries
Python Examples - Integrate the API into your Python data pipelines
PowerBI Connector (beta) - Browse and load time series in Power BI, no WarpScript required
Grafana Plugin (beta) - Query Nexalis from Grafana dashboards, no WarpScript required

API Endpoint

The Nexalis real-time API is accessible via your dedicated endpoint:

https://yourcompany.app.nexalis.io/api/v0/exec

Replace yourcompany with your organization’s name. All requests must be sent via HTTP POST with WarpScript code in the request body.

Authentication

All API requests require authentication using a READ token.

Contact contact@nexalis.io to obtain your READ token.

Data Structure

A tag is stored as a Geo Time Series (GTS). Each GTS is uniquely identified across all your data with its labels, namely:

siteName - site where the device is located
deviceModel - manufacturer and model
deviceID - unique identifier of the device
dataPoint - device‑specific identifier (e.g., Modbus register, OPC UA tag)

Each GTS also has attributes which add context and describe a tag, such as:

description - manufacturer‑provided description
protocol - communication protocol used

Standardized Tags

Nexalis standardizes some tags by contextualizing and translating them to the Nexalis data model, which is based on IEC 61850. Standardized tags will have additional attribute columns:

assetType - standardized device type (e.g., Solar inverter, Storage inverter, Meteo station, Meter, Wind turbine, etc.)
subDeviceID - distinguishes devices when connected via proxy/gateway
logicalNode - standardized function type (e.g., MMDC: DC Measurements)
dataObject - standardized tag (e.g., PhV: phase voltage)
subDataObject - finer breakdown (e.g., phsA: phase A)
engUnits - standardized engineering units
multiplier - scaling multiplier for unit conversion (from scada unit to Nexalis engUnits)
adder - scaling offset for unit conversion (from scada unit to Nexalis engUnits)
measurementType - Analog or Discrete

Values are stored raw, exactly as sent by the data source. multiplier and adder are what convert them into engUnits, and that conversion is not applied automatically - see FETCH below.

Field Availability: Nexalis API only returns non-empty labels and attributes. While labels are always present for identification, standardized attributes (such as assetType, logicalNode, dataObject) are only included for tags that have been mapped to the Nexalis data model. Additionally, unit-related attributes (engUnits, adder, multiplier) are typically omitted for discrete measurement types, as these data points generally do not have a unit.

Core Query Functions

The API uses WarpScript, a stack-based language for time-series operations. Two main functions are available:

FIND - Discover Available Metrics

Search for time-series matching specific criteria without fetching values. Useful for exploring what data is available. Example query:

{
  'token' 'YOUR_READ_TOKEN'
  'class' 'nx.value'
  'labels' { 'assetType' 'INV' 'dataObject' 'TotW' }
} FIND

Output:

[[{"c":"nx.value",
"l":{"siteName":"TX_001","deviceModel":"Satcon",".app":"nexalis","deviceID":"01234","dataPoint":"42"},
"a":{"dataObject":"TotW","subDataObject":"","protocol":"modbus_tcp","multiplier":"0.1","logicalNode":"MMXU","measurementType":"Analog","description":"AC Power, Generated = Export, from Inverter","engUnits":"kW","adder":"0","nx-agent-id":"v1.1.5#xxxx","assetType":"INV","subDeviceID":"BLK_001_23"},
"la":0,
"v":[]}]]

FIND returns class ("c":{...}), labels ("l":{...}), attributes ("a":{...}), and an empty value field ("v":[]). How to do it in python

FETCH - Retrieve Time-Series Data

Fetch actual values for specific time ranges and metrics. Example query:

{
  'token' 'YOUR_READ_TOKEN'
  'class' 'nx.value'
  'labels' { 'assetType' 'INV' 'dataObject' 'TotW' }
  'start' '2026-01-15T00:00:00Z'
  'end' '2026-01-15T01:00:00Z'
} FETCH

Output:

[[{"c":"nx.value",
"l":{"siteName":"TX_001","deviceModel":"Satcon",".app":"nexalis","deviceID":"01234","dataPoint":"42"},
"a":{"dataObject":"TotW","subDataObject":"","protocol":"modbus_tcp","multiplier":"0.1","logicalNode":"MMXU","measurementType":"Analog","description":"AC Power, Generated = Export, from Inverter","engUnits":"kW","adder":"0","nx-agent-id":"v1.1.5#xxxx","assetType":"INV","subDeviceID":"BLK_001_23"},
"la":0,
"v":[[1768438794869000,0,348],[1768438790168000,0,346],[1768438784989000,0,350], ... ,[1768435210217000,0,405],[1768435200214000,0,386]]}]]

Here, each sub-list in the “v” (value) field is a measurement, where the first element is the microseconds unix timestamp, and the last element is the actual value.

FETCH returns raw, unscaled values. Values are stored exactly as the data source sent them. The multiplier and adder attributes convert them into the units named in engUnits, and FETCH does not apply that conversion. In the output above the dataPoint carries "multiplier":"0.1" and "engUnits":"kW", so the raw value 348 is 34.8 kW, not 348 kW. Reading a FETCH result as though it were already in engUnits overstates it by the multiplier.

Apply the conversion with @nexalis/scale:

{
  'token' 'YOUR_READ_TOKEN'
  'class' 'nx.value'
  'labels' { 'assetType' 'INV' 'dataObject' 'TotW' }
  'start' '2026-01-15T00:00:00Z'
  'end' '2026-01-15T01:00:00Z'
} FETCH
@nexalis/scale

The @nexalis/fetch_trapezoidal_averages and @nexalis/fetch_bucketized macros already scale their output - they call @nexalis/scale internally unless you pass 'scaling' false. A plain FETCH is the only query path that returns unscaled values, so mixing raw FETCH results with macro results in the same report gives readings that differ by the multiplier. And because @nexalis/scale is not idempotent, never apply it on top of a macro result.

How to do it in python

Both FIND and FETCH functions support:

Regular expressions for pattern matching (prefix with ~)
Multiple filters on labels and attributes (both passed in the “labels” field)

Additionally, FETCH supports:

Flexible time ranges with ISO8601 strings or microseconds unix time

Best Practices

FIND first, then FETCH per tag

When querying multiple tags, always discover before you fetch:

Use FIND with label filters to get the list of matching tags and their exact identifiers
FETCH each tag individually using deviceID + dataPoint from the FIND results

import requests

ENDPOINT = "https://yourcompany.app.nexalis.io/api/v0/exec"
READ_TOKEN = "YOUR_READ_TOKEN"

# Step 1: discover all matching tags
find_query = f"""
{{
  'token' '{READ_TOKEN}'
  'class' 'nx.value'
  'labels' {{ 'siteName' 'TX_001' 'assetType' 'INV' 'dataObject' 'TotW' }}
}} FIND
"""
tags = requests.post(
    ENDPOINT,
    headers={{"Content-Type": "text/plain; charset=UTF-8"}},
    data=find_query
).json()[0]

# Step 2: fetch each tag individually over the full time range
for gts in tags:
    l = gts["l"]
    fetch_query = f"""
    {{
      'token' '{READ_TOKEN}'
      'class' 'nx.value'
      'labels' {{ 'deviceID' '{l["deviceID"]}' 'dataPoint' '{l["dataPoint"]}' }}
      'start' '2026-01-01T00:00:00Z'
      'end' '2026-02-01T00:00:00Z'
    }} FETCH
    @nexalis/scale
    """
    data = requests.post(
        ENDPOINT,
        headers={{"Content-Type": "text/plain; charset=UTF-8"}},
        data=fetch_query
    ).json()
    # process data...

This pattern keeps each request small and predictable. If a single tag fails, the others are unaffected. For concurrent fetching, wrap the loop in a ThreadPoolExecutor.

Go deep, not wide

Timeseries databases are optimized for long reads on a single tag. One tag over a long period is always faster than many tags at once.

Avoid	Prefer
Fetch 50 tags over 1 month in one request	Fetch 1 tag over 1 month, repeat for each tag
Broad FETCH with only `assetType` + `dataObject`	Narrow FETCH with `deviceID` + `dataPoint`

Filter as specifically as possible

Every label you add reduces the number of series the API needs to scan. Always include siteName when targeting a specific site, and add deviceID or dataPoint when you know them.

Nexalis Custom Macros

Nexalis provides ready-to-use macros that simplify common time-series operations:

@nexalis/scale - Apply unit conversions and calibrations
@nexalis/fetch_trapezoidal_averages - Fetch and compute trapezoidal averages for irregularly-sampled data

For detailed examples of using these macros, see the Nexalis Macros guide.

Custom Macros

You can also build your own WarpScript macros to encapsulate complex logic and reuse common query patterns across your organization.

Filtering Data

The labels parameter in both FIND and FETCH queries accepts filters on both labels and attributes, allowing you to precisely target the data you need.

Basic Filtering

Filter by exact matches on any label or attribute field:

{
  'token' 'YOUR_READ_TOKEN'
  'class' 'nx.value'
  'labels' { 
    'siteName' 'TX_001'
    'assetType' 'INV'
    'dataObject' 'TotW'
  }
} FIND

Regular Expression Filtering

Prefix filter values with ~ to use regular expressions for pattern matching:

{
  'token' 'YOUR_READ_TOKEN'
  'class' 'nx.value'
  'labels' { 
    'siteName' '~TX_.*'           // Match any site starting with TX_
    'deviceID' '~INV-(1|2|3)'     // Match INV-1, INV-2, or INV-3
    'dataObject' '~(.*W$|.*Tmp.*)'         // Match any dataObject ending with W or containing Tmp
  }
} FIND

Common Regex Patterns

Pattern	Description	Example
`~.*`	Match anything (wildcard)	`'siteName' '~.*'`
`~^TX_`	Starts with “TX_“	`'siteName' '~^TX_'`
`~.*_001$`	Ends with “_001”	`'deviceID' '~.*_001$'`
`~(INV\|METER)`	Match multiple values	`'assetType' '~(INV\|METER)'`

Remember to escape special regex characters when needed. The tilde (~) prefix indicates that the value should be interpreted as a regular expression rather than an exact string match.

API Integration

The Nexalis real-time API can be queried from any tool or programming language that supports HTTP requests. Simply send a POST request with:

URL: Your endpoint (https://yourcompany.app.nexalis.io/api/v0/exec)
Headers: X-Warp10-Token: YOUR_READ_TOKEN
Body: WarpScript code (plain text)

This works seamlessly with cURL, Python, PowerBI, and any other HTTP-capable tool. Nexalis also provides ready-made integrations that wrap these calls for you: the Grafana plugin and the Excel add-in.

Learn More

Nexalis Macros Examples - Detailed macro usage and patterns
Python Integration - Build data pipelines with Python
PowerBI Connector - Build dashboards from the Power BI Navigator
Grafana Plugin - Install the plugin and build dashboards from dropdowns

For API access and support, contact contact@nexalis.io

Overview

Nexalis Cloud

Nexalis Agent

Performance

Quick Start Examples

API Endpoint

Authentication

Data Structure

Standardized Tags

Core Query Functions

FIND - Discover Available Metrics

FETCH - Retrieve Time-Series Data

Best Practices

FIND first, then FETCH per tag

Go deep, not wide

Filter as specifically as possible

Nexalis Custom Macros

Custom Macros

Filtering Data

Basic Filtering

Regular Expression Filtering

Common Regex Patterns

API Integration

Learn More

​Quick Start Examples

​API Endpoint

​Authentication

​Data Structure

​Standardized Tags

​Core Query Functions

​FIND - Discover Available Metrics

​FETCH - Retrieve Time-Series Data

​Best Practices

​FIND first, then FETCH per tag

​Go deep, not wide

​Filter as specifically as possible

​Nexalis Custom Macros

​Custom Macros

​Filtering Data

​Basic Filtering

​Regular Expression Filtering

​Common Regex Patterns

​API Integration

​Learn More

Quick Start Examples

API Endpoint

Authentication

Data Structure

Standardized Tags

Core Query Functions

FIND - Discover Available Metrics

FETCH - Retrieve Time-Series Data

Best Practices

FIND first, then FETCH per tag

Go deep, not wide

Filter as specifically as possible

Nexalis Custom Macros

Custom Macros

Filtering Data

Basic Filtering

Regular Expression Filtering

Common Regex Patterns

API Integration

Learn More