API Reference
Reference documentation for Ardexa's RESTful API
Regions
Ardexa runs clouds in several regions, each on its own subdomain. Send every request to the cloud your workgroup belongs to — app.ardexa.com or eur1.ardexa.com. A token issued by one region is not valid on another.
Authentication
Every endpoint here requires an Ardexa API token, sent as an Authorization: Bearer <token> header:
curl -H "Authorization: Bearer $ARDEXA_TOKEN" \
"https://app.ardexa.com/api/v1/devices/my-workgroup"When a request is refused
A 403 response carries a JSON body with a code and a message naming what was required:
workgroup_not_in_credential
The token does not cover that workgroup. Check the workgroup ID, and that you are calling the right region.
insufficient_permissions
The token covers the workgroup but lacks the permission this endpoint needs.
devgroup_restricted
The token is restricted to a different device group.
Devices
Returns every device in the workgroup, each with its reported metadata and stored settings. A token restricted to a device group sees only that group's devices.
Use nameonly when all you need is a lookup of IDs to names, and compact=false to have each device's field definitions expanded rather than returned as references — see GET /devices/{orgName}/{device}. The expanded response is larger, since shared definitions are then repeated per scenario.
This is where a workgroup read gets expensive: every entry carries its device's whole meta document, and a single device's can be megabytes. Use meta to narrow it to the keys you read, or to drop it entirely.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Restrict the list to one device group, given as the group's _id
from GET /orgs/{orgName}/device-groups. A value that is not a valid
ID is rejected with 400. A token already restricted to a device
group may only name its own group.
Set to false to have shared field definitions in each device's
meta expanded in place, rather than returned as references. See
the endpoint description.
trueNarrow, or drop, each device's meta document. Omit the parameter
and the whole document is returned, as it always has been.
| Value | Each device's meta |
|---|---|
| (parameter absent, or empty) | The whole document |
true, 1 | The whole document, said explicitly |
false, 0 | Not returned — the meta key is absent |
a,b,c | Only those top-level keys, each absent if the device has none |
Any other value is read as a key list, and a repeated parameter
(meta=a&meta=b) means the same as meta=a,b.
The saving is on the wire, not in the database: the metadata is
already held in memory, so meta=false costs the same read and
sends hundreds of bytes per device instead of megabytes.
Include this parameter (any value) to return only id and name
for each device. It takes precedence over meta, which is then
ignored.
The devices in the workgroup
The fields below are the ones useful to an integration;
further internal fields may also be present. With
nameonly, only id and name are returned.
Device ID, used as the device path parameter elsewhere
Whether the device currently holds a connection to the cloud
The device's last reported configuration, in the same
shape as GET /devices/{orgName}/{device}. {} for a
device that has never reported metadata, and null for
one the cloud knows of but has no record for.
Absent entirely under meta=false; under a key list,
an object holding only the keys asked for — {} for a
device that has none of them, or none at all.
The device's stored settings, keyed by setting name
Agent version running on the device
Invalid devGroup
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error
GET /api/v1/devices/{orgName} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "826d91ab-857e-4896-a877-224e387af6f0",
"name": "4343 - HEM 593 R-Truck",
"online": true,
"settings": {
"site": "Northern Depot"
}
}
]Returns a single device's identity, whether it is currently connected, and its latest reported metadata.
The identity fields are the same ones the workgroup list returns per device, so version — what the agent running on the device can do — no longer needs a whole-workgroup read. meta narrows or drops the metadata, which is the bulk of the response and can be megabytes.
The meta object is what the device last reported about how it collects data. It holds a list of scenarios per collection method:
run
Runs a command on a schedule
tail
Watches a text file for new lines
watch
Detects changes to files
unix_socket
Listens for events on a socket
dynamic
Scenarios the device detected for itself
Every scenario names the table and source its readings go to, which is how you work out what to search for a given device.
Reading a scenario's fields
This endpoint returns field definitions exactly as the device stored them, so a scenario's fields may be any of:
an array of field definitions; or
a string naming a top-level property of
metaholding an array shared by several scenarios; ora string in
table.sourceform, naming another scenario whose fields to reuse.
When fields is a string, resolve it against the meta property of that name, or against the scenario whose table and source match. To skip that work, call GET /devices/{orgName}?compact=false, which returns the same metadata with the references already expanded.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
Narrow, or drop, the meta document. Omit the parameter and the
whole document is returned, as it always has been.
| Value | meta in the response |
|---|---|
| (parameter absent, or empty) | The whole document |
true, 1 | The whole document, said explicitly |
false, 0 | Not returned — the meta key is absent |
a,b,c | Only those top-level keys, each absent if the device has none |
Any other value is read as a key list, and a repeated parameter
(meta=a&meta=b) means the same as meta=a,b.
meta=false is also the one value that succeeds for a device that
has never reported metadata; see the 500 response.
Device metadata
The fields below are the ones useful to an integration; further internal fields may also be present.
Device ID. id holds the same value — the workgroup list
spells it that way — so a caller may read either.
Device ID, used as the device path parameter elsewhere
Whether the device currently holds a connection to the cloud
Agent version running on the device
The agent's working directory on the device
Whether the agent is running in fallback mode
Why the agent fell back, when fallback is true
When the device's certificate expires. A device whose certificate has expired cannot connect.
Whether this is a cloud-hosted device (CED)
Further properties recorded for the device
The device's last reported configuration. Scenario lists are keyed by collection method (run, watch, tail, unix_socket, dynamic).
Absent entirely under meta=false; under a key list, an
object holding only the keys asked for — {} for a
device that has none of them, or none at all.
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Device not found, or outside the token's device group (dev035)
Internal server error (dev019, dev021). A device that has never
reported metadata answers dev021 here, since there is no document
to return — unless the caller passed meta=false, which asks for
none and so succeeds.
GET /api/v1/devices/{orgName}/{device} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "text",
"id": "text",
"name": "text",
"online": true,
"version": "text",
"platform": "text",
"os": "text",
"cwd": "text",
"fallback": true,
"fallbackError": "text",
"notAfter": "2026-01-01T00:00:00.000Z",
"ced": true,
"info": {},
"meta": {}
}The same health summary as the workgroup-wide status endpoint, for a single device — when it was last online or offline, its clock drift, and any table and source combinations that have stopped arriving.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
Status for the device
Timestamp the device last came online
Timestamp the device last went offline
Difference between the device's clock and the cloud's, in seconds. A large value means timestamps on that device's data may be wrong.
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Device not found, outside the token's device group, or no status has been recorded for it yet
Internal server error
GET /api/v1/devices/{orgName}/{device}/status HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"online": "text",
"offline": "text",
"clockDiff": "text",
"missing": [
{
"table": "text",
"source": "text",
"date": "text"
}
]
}Returns a health summary for every device in the workgroup, keyed by device ID — when each device was last online or offline, how far its clock has drifted, and which table and source combinations have stopped arriving.
Use this to check whether a device is still reporting before concluding that a search returned nothing because there is no data.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Status for each device, keyed by device ID. Empty object when there are no devices to report on.
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error
GET /api/v1/devices/{orgName}/device/status HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": {
"online": "text",
"offline": "text",
"clockDiff": "text",
"missing": [
{
"table": "text",
"source": "text",
"date": "text"
}
]
}
}Retrieves the most recent data values for a specific device, optionally grouped by source or device. Supports filtering by source and specific fields. The search window defaults to the last 24 hours; supply startTime/endTime or days to look further back.
For every device in the workgroup at once use /devices/{orgName}/device/latestValues. For a single named stream, /devices/{orgName}/{device}/latest/{stream} is cheaper.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
Name of the data table to query
Filter results by specific data source
Filter to only include records where this field exists. Accepts a single field or a comma-separated list, in which case every listed field must exist.
Require each field named by field to be non-zero as well as present. Used for last-known-position lookups, where a zero coordinate means "no fix" rather than a location.
falseReturn only the fields named by field (plus event_time) instead of the whole record. Requires field. Off by default, so existing callers keep receiving full records.
falseHow to group the results - by source or by device
sourcePossible values: Start of the search window (ISO 8601). Must be supplied together with endTime. Defaults to the start of the previous day.
End of the search window (ISO 8601). Must be supplied together with startTime.
Look back this many days instead of supplying an explicit window. Ignored when startTime/endTime are given, and clamped to 400 days.
Comma-separated device ids to narrow the query to, maximum 100. Always intersected with the caller's device group. Omit to include every device in scope.
Maximum number of devices to return, capped at 10000 (the default).
Latest values retrieved successfully
When groupBy=source - object keyed by deviceId containing an object keyed by source name with the latest record. When groupBy=device - object keyed by deviceId with the latest record directly
Invalid groupBy parameter (must be 'source' or 'device'), malformed startTime/endTime (lv001, lv002), invalid days (lv003), too many device ids (lv004), or invalid limit (lv005)
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Device not found or not accessible in device group
Internal server error
GET /api/v1/devices/{orgName}/{device}/latestValues?table=text HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device1": {
"source1": {
"event_time": "2025-11-13T10:30:00Z",
"temperature": 25.5,
"humidity": 60
},
"source2": {
"event_time": "2025-11-13T10:31:00Z",
"voltage": 12.3
}
}
}Retrieves the most recent data value per device (or per source) for all accessible devices, optionally grouped by source or device. Supports filtering by source and specific fields. The search window defaults to the last 24 hours; supply startTime/endTime or days to look further back, which is how a last-known value is resolved for devices that have been offline.
There are four ways to read a latest value; this one covers every device at once. For one device use /devices/{orgName}/{device}/latestValues, for one named stream use /devices/{orgName}/{device}/latest/{stream}, and for a fixed set of streams read straight from cache use /devices/{orgName}/device/cachedLatestValues.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the data table to query
Filter results by specific data source
Filter to only include records where this field exists. Accepts a single field or a comma-separated list, in which case every listed field must exist.
Require each field named by field to be non-zero as well as present. Used for last-known-position lookups, where a zero coordinate means "no fix" rather than a location.
falseReturn only the fields named by field (plus event_time) instead of the whole record. Requires field. Off by default, so existing callers keep receiving full records.
falseHow to group the results - by source or by device
sourcePossible values: Start of the search window (ISO 8601). Must be supplied together with endTime. Defaults to the start of the previous day.
End of the search window (ISO 8601). Must be supplied together with startTime.
Look back this many days instead of supplying an explicit window. Ignored when startTime/endTime are given, and clamped to 400 days.
Comma-separated device ids to narrow the query to, maximum 100. Always intersected with the caller's device group. Omit to include every device in scope.
Maximum number of devices to return, capped at 10000 (the default).
Latest values retrieved successfully
When groupBy=source - object keyed by deviceId, each containing an object keyed by source name with the latest record. When groupBy=device - object keyed by deviceId with the latest record directly
Invalid groupBy parameter (must be 'source' or 'device'), malformed startTime/endTime (lv001, lv002), invalid days (lv003), too many device ids (lv004), or invalid limit (lv005)
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error
GET /api/v1/devices/{orgName}/device/latestValues?table=text HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"device1": {
"source1": {
"event_time": "2025-11-13T10:30:00Z",
"temperature": 25.5,
"humidity": 60
},
"source2": {
"event_time": "2025-11-13T10:31:00Z",
"voltage": 12.3
}
}
}Get cached latest values for multiple device streams
Retrieves the most recent cached data values for the device streams you name, read straight from the cache rather than queried. Supports filtering by device group membership.
Requires the latest-values addon. Without it every request is refused with 403 — use /devices/{orgName}/device/latestValues instead, which queries the data directly and needs no addon.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Cached values retrieved successfully
Object keyed by deviceId, then by table, then by source, containing the requested field values
Bad request - Workgroup not found
Missing, expired or invalid token
No access to this workgroup, or the latest-values addon is not enabled for it
Internal server error
POST /api/v1/devices/{orgName}/device/cachedLatestValues HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 220
{
"streams": [
{
"deviceId": "device1",
"table": "sensors",
"source": "temp_sensor",
"field": "temperature",
"type": "decimal"
},
{
"deviceId": "device1",
"table": "sensors",
"source": "humidity_sensor",
"field": "humidity",
"type": "integer"
}
]
}{
"device1": {
"sensors": {
"temp_sensor": {
"temperature": 25.5
},
"humidity_sensor": {
"humidity": 60
}
}
}
}Returns the single most recent record a device produced for one stream, identified by table and source. Use this when you want the current value for a known stream rather than a range of history — it is cheaper than a search, and is served from cache when the latest-values addon is enabled for the workgroup.
Find a device's table and source names in its metadata, at GET /devices/{orgName}/{device}.
For every value a device last reported, rather than one stream, use /devices/{orgName}/{device}/latestValues.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
The stream, written as table.source. A third part —
table.source.field — narrows the result to records carrying that
field, and is accepted only for CSV-type scenarios.
Data_1s_Log.Data_1s_LogThe most recent record for the stream
The stream exists but holds no records
Malformed stream name (fewer than two or more than three parts), or a field was named on a scenario that is not CSV-type
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
No such stream on this device, or the named field is not part of the scenario
Internal server error
GET /api/v1/devices/{orgName}/{device}/latest/{stream} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Metadata
Returns every stored setting for one device. Device settings are values you set in the cloud — site name, location, asset references and similar — as distinct from the meta object on the device metadata endpoint, which is what the device itself reports.
Settings are also what device groups can be built from, so the keys present here determine how devices can be grouped and filtered.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
The device's settings
The setting's name
The stored value. Type depends on the setting — a string, number, boolean, object or array.
Present on device settings only
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error (set001)
GET /api/v1/devices/{orgName}/{device}/settings HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "text",
"key": "text",
"value": null,
"deviceId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
]Returns a single stored setting for a device, by key.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device ID
The setting's name
The setting
The setting's name
The stored value. Type depends on the setting — a string, number, boolean, object or array.
Present on device settings only
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
No setting with that key on this device
Internal server error (set002)
GET /api/v1/devices/{orgName}/{device}/settings/{key} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "text",
"key": "text",
"value": null,
"deviceId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}Returns every stored setting for the workgroup — configuration that applies across all its devices, such as the CSV delimiter used for exports or the site definitions used for metering.
These are workgroup-wide, unlike the per-device settings at GET /devices/{orgName}/{device}/settings.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
The workgroup's settings
The setting's name
The stored value. Type depends on the setting — a string, number, boolean, object or array.
Present on device settings only
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error (set001)
GET /api/v1/orgs/{orgName}/settings HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "text",
"key": "text",
"value": null,
"deviceId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}
]Returns a single workgroup setting, by key.
For a token restricted to a device group, the meterSites setting is narrowed to the sites whose devices all fall inside that group. Other settings are returned whole.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
The setting's name
The setting
The setting's name
The stored value. Type depends on the setting — a string, number, boolean, object or array.
Present on device settings only
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
No setting with that key in this workgroup
Internal server error (set002)
GET /api/v1/orgs/{orgName}/settings/{key} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "text",
"key": "text",
"value": null,
"deviceId": "text",
"createdAt": "2026-01-01T00:00:00.000Z",
"updatedAt": "2026-01-01T00:00:00.000Z"
}Returns the workgroup's device groups. A device group is a named subset of devices; searches and device listings can be scoped to one.
Use the _id from this list as the devGroup parameter on GET /devices/{orgName}.
A token restricted to a device group sees only that one group.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
The workgroup's device groups
Device group ID. Pass this as the devGroup parameter when listing devices.
How membership is decided — for example by an explicit device list, by a device setting (META), or by device and source (SRC).
The membership definition, whose shape depends on composition.
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error
GET /api/v1/orgs/{orgName}/device-groups HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"_id": "text",
"name": "text",
"composition": "text",
"value": null
}
]Returns a single device group, including the definition of which devices belong to it.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Device group ID
The device group
Device group ID. Pass this as the devGroup parameter when listing devices.
How membership is decided — for example by an explicit device list, by a device setting (META), or by device and source (SRC).
The membership definition, whose shape depends on composition.
Missing, expired or invalid token
No access to this workgroup, or the token is restricted to a different device group
Device group not found
Internal server error
GET /api/v1/orgs/{orgName}/device-groups/{devgroup} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"_id": "text",
"name": "text",
"composition": "text",
"value": null
}Search
Returns the names of every table the workgroup has data in. Use these names as the table path parameter on the search endpoints.
audit_logs appears only for tokens with the Read audit logs permission; everyone else gets the list without it.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Table names
["Data_1s_Log","daily_energy","status"]Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error (tbl001, tbl002, tbl003)
GET /api/v1/tables/{orgName} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
"Data_1s_Log",
"daily_energy",
"status"
]Describes one table: how many records it holds and what columns are available, with each column's data type and unit of measure. Call this before searching to discover which field names and date fields the table supports.
Reading the audit_logs table also needs the Read audit logs permission.
Units are resolved from the reporting devices' metadata. Where two devices report the same column with different units, the column also carries a conflict entry listing them.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the table
Table information
Number of records in the table
Missing, expired or invalid token
No access to this workgroup, or no Read audit logs permission for the audit_logs table
Table not found, or the table holds no records
Internal server error (tbl002, tbl007)
GET /api/v1/tables/{orgName}/{table} HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"count": 1500000,
"fields": {
"event_time": {
"type": "date"
},
"Power": {
"type": "double",
"units": "kW"
}
}
}Returns the devices whose configuration sends data to this table, keyed by device ID, with each device's latest metadata. Use it to find which devices to filter on before searching.
A token restricted to a device group sees only that group's devices.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the table
Devices reporting to the table, keyed by device ID
The device's latest reported metadata, with each scenario's
fields already expanded — unlike
GET /devices/{orgName}/{device}, which returns them as the
device stored them.
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
Internal server error (tbl008)
GET /api/v1/tables/{orgName}/{table}/devices HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": {}
}Runs a query against one of the workgroup's data tables and returns the matching records. This is the primary endpoint for extracting data.
By default the oldest 50 records are returned. Ask for sort=-event_time when you want the most recent ones instead. Narrow the result with timeframe and filters, choose columns with fields, and page through large result sets with scroll.
Reading the audit_logs table also needs the Read audit logs permission.
If a search returns no records, /devices/{orgName}/device/status shows whether the devices are still reporting.
Retrieving more than 10,000 records
One request returns at most 10,000 records. To read more, add scroll and page through the result with /tables/{orgName}/{table}/search/scroll. A scroll has no total limit — it walks the whole result set however large it is.
rows sets the size of every scroll page, not just the first response. Send rows=10000 alongside scroll to keep the number of round trips down.
There is no offset, page or page-size parameter, and the response carries no next-page URL. scroll is the only way to page.
A search has no server-side time limit, so a broad query takes as long as it needs rather than timing out.
Timeframe expressions
timeframe is either a single expression — meaning "from then onward", with no upper bound — or a range written <start> until <end>. Either side accepts:
ISO 8601 timestamp
2026-08-01, 2026-08-01T00:00:00Z, 2026-08-01 09:30:00
Keyword
now, today
Relative
7 days ago, three days ago, 6 months ago
Calendar edge
beginning of last month, end of yesterday, beginning of June 2026
Relative units are second, minute, hour, day, week, month and year, and the count may be spelled out up to thirty-one. Calendar periods are today, yesterday, this/last/next week, month or year, or a named month and year; start of also works in place of beginning of. Prefixing a relative expression with 0am anchors it to midnight of that day.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the table to search. Use /tables/{orgName} to list the available tables.
The period to search, for example "7 days ago" or "2026-08-01 until 2026-08-08". Omit to search all time. See the endpoint description for the full set of expressions.
7 days agoFilter conditions, each sent as a JSON object serialised to a string — not as nested query parameters. Repeat the parameter to apply several; they are combined with AND.
filters={"field":"Power","operator":">","value":0}
Each object is either a single condition (field, operator,
value) or a group (operator of AND or OR, plus a nested
filters array). Operators are >, >=, <, <=, =, !=,
BETWEEN, NOT BETWEEN, LIKE, NOT LIKE, IN, NOT IN,
EXISTS and IS MISSING. value is required for all except
EXISTS and IS MISSING; use an array for IN, NOT IN,
BETWEEN and NOT BETWEEN. On a date column, value accepts the
same expressions as timeframe.
{"field":"Power","operator":">","value":0}Columns to return. Repeat the parameter for several. Omit to return every column. Maximum 2000 fields per query.
Columns to sort by. A bare name sorts ascending; prefix it with -
to sort descending.
The default is event_time ascending — that is, oldest records
first. To get the most recent records, ask for -event_time.
Sorting on a column the table does not have is rejected (ser905).
["event_time"]Number of records to return. Maximum 10000; use scroll for more.
With scroll, this sets the size of every page, not just the first
response.
50Include this parameter (any value) to open a scroll context for
paging through more records than rows allows. The response then
carries a scroll_id. Cannot be combined with aggs.
A scroll has no total record limit; only the per-page rows cap
applies.
Aggregations to compute instead of returning raw records, each sent
as a JSON object serialised to a string. Repeat for several. Cannot
be combined with scroll.
aggs={"field":"Power","type":"avg"}
Each object needs a type — stats, extended_stats, sum,
avg, date_histogram, histogram, top_hits or range — and a
field (or fields for several). Add groupBy to break the
result down by other columns, interval for the histogram types,
and perDevice to split a histogram by device.
Send rows=0 to get the aggregations without any record data.
{"field":"Power","type":"avg"}Which date column timeframe applies to. Must be a date field on
the table.
event_timeIANA timezone name used to resolve timeframe and date filter
values, for example Europe/Berlin. An unrecognised name falls back
to Etc/UTC rather than failing.
Etc/UTCSet to latest to search only the most recent index. Faster for
recent data, but will not find older records.
Search results
The matching rows, one object per record.
Total number of records matching the query, which may exceed
rows. Every scroll page repeats the same total; it does not
count down as you page.
Query execution time in milliseconds.
Present only when scroll was requested. Pass it to
/tables/{orgName}/{table}/search/scroll to fetch the next page.
Each response returns a fresh id, and each call resets the
context's 45-second expiry.
Present only when aggs was requested.
Invalid query. The response body carries one of these codes:
| Code | Meaning |
|---|---|
| ser100 | rows above 10000 |
| ser101 | Malformed sort |
| ser102 | Malformed filters |
| ser103 | Malformed timeframe, or dateField is not a date column |
| ser104 | Malformed aggs |
| ser105 | Malformed fields |
| ser106 | scroll and aggs used together |
| ser108 | More than 2000 fields |
| ser901 | An aggregation names a column the table does not have |
| ser902 | Unknown aggregation type |
| ser903 | Aggregation is missing an argument, such as interval |
| ser904 | A filter names a column the table does not have |
| ser905 | sort names a column the table does not have |
| ser906 | An aggregation groupBy names a column the table does not have |
| ser907 | Bad filter structure, or a nested aggregation names an unknown column |
For the "column the table does not have" codes, use /tables/{orgName}/{table} to list the table's columns.
Missing, expired or invalid token
No access to this workgroup, or no Read audit logs permission for the audit_logs table. The body names which.
Table not found (tbl002), or device group not found (devgrp001)
Internal server error
GET /api/v1/tables/{orgName}/{table}/search HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"records": [
{}
],
"totalRecords": 1,
"took": 1,
"scroll_id": "text",
"aggregations": {}
}Continues a search started with the scroll parameter. Pass the scroll_id from the previous response; each response returns a fresh id to use for the page after it. Keep calling until records comes back empty — a response can still carry a scroll_id once the records have run out, so an empty records is the signal to stop.
Each page is rows records, the value given on the initiating search.
A scroll context expires 45 seconds after the last call, not 45 seconds from the start, so a scroll of any length is fine as long as the gap between calls stays under that. Once it expires the id is no longer valid and the search must be restarted.
An Ardexa API token, sent as Authorization: Bearer <token>.
Workgroup ID
Name of the table being searched
The scroll_id returned by the previous search or scroll response
The next page of results
The matching rows, one object per record.
Total number of records matching the query, which may exceed
rows. Every scroll page repeats the same total; it does not
count down as you page.
Query execution time in milliseconds.
Present only when scroll was requested. Pass it to
/tables/{orgName}/{table}/search/scroll to fetch the next page.
Each response returns a fresh id, and each call resets the
context's 45-second expiry.
Present only when aggs was requested.
scroll_id was not supplied
Missing, expired or invalid token
No access to this workgroup, or the token lacks the permission this endpoint needs
The scroll id is unknown or has expired
Internal server error
GET /api/v1/tables/{orgName}/{table}/search/scroll?scroll_id=text HTTP/1.1
Host: app.ardexa.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"records": [
{}
],
"totalRecords": 1,
"took": 1,
"scroll_id": "text",
"aggregations": {}
}Last updated
Was this helpful?