Everything in the App is also available from MTConnect Server's HTTP API, for integration with other applications. This page covers reading the data Collection has stored: the collected Devices and their models, current and historical Observations, MTConnect Assets, Connection Status, and statistics.
Getting Started
Base URL
http://{server}:8490/api
8490is the default port. Use the HTTP Port entered when MTConnect Server was installed./apiis the route when installed with the installer. When the MTConnect Server Packages are installed on an existing TrakHound Instance, it's/api/mtconnect-server.
The routes on this page are relative to the Base URL. For example, the Devices are read from http://localhost:8490/api/collection/data/devices.
API Keys
On a standalone install, every request needs an API Key. Create one in the App under System > API Keys, then send it in the X-API-Key header,
or as Authorization: Bearer <key>. Without a valid Key the API returns 401.
A Key can use the whole API, but not the App or the Instance's System API, and it can't manage other Keys.
When MTConnect Server is installed as Packages on your own TrakHound Instance, the API follows that Instance's Security Profiles.
What Can Be Read
The data API reads what Collection has stored in its Tables, so a Device's data is available once it's collected with a Tables Profile.
| Route | Data |
|---|---|
collection/data/devices | Devices, Device models, Components, DataItems, and Observations (current and historical) |
collection/assets | MTConnect Assets (ex. Cutting Tools) |
collection/connections | The Connection Status of each Device, and its history |
collection/statistics | Observation and Data Retention statistics |
Requests and Responses
- Requests are
GETrequests (except where noted), and responses are JSON. - A request for data that doesn't exist (or a Device with no data yet) returns
404. A missing or invalid parameter returns400. - Properties with a default value (
false,0, ornull) are left out of responses. For example,isUnavailableonly appears when it'strue. - Timestamps are UTC, in ISO 8601 format (ex.
2026-10-08T14:30:05.1234567Z).
Time Parameters
Parameters that take a time (ex. start and end) accept:
| Format | Example |
|---|---|
ISO 8601 (UTC with a Z, or the server's local time without one) | 2026-10-08T14:00:00Z |
| Unix time (seconds, milliseconds, or nanoseconds) | 1791468000 |
| A relative time | now, today, yesterday, this-week, last-month |
A duration ago (s, m, h, d, y) | 30m-ago, 1h-ago, 7d-ago |
Devices
| Route | Returns |
|---|---|
GET collection/data/devices | The collected Devices, with each one's uuid, id, name, and mtconnectVersion |
GET collection/data/devices/{deviceUuid} | One Device |
GET collection/data/devices/{deviceUuid}/model | The full Device model (the same information as an MTConnect Probe), as a tree of Components and DataItems |
GET collection/data/devices/{deviceUuid}/components | A flat list of the Components |
GET collection/data/devices/{deviceUuid}/dataitems | A flat list of the DataItems, with each one's id, parentId, name, category, type, subType, representation, units, and nativeUnits |
[
{
"uuid": "OKUMA.Lathe.123456",
"id": "d1",
"name": "OKUMA-Lathe",
"mtconnectVersion": "2.3"
}
]
Current Values
GET collection/data/devices/{deviceUuid}/observations
GET collection/data/devices/{deviceUuid}/{dataItemId}/observations
Without a time range, these return the latest value of each DataItem of the Device (the same information as an MTConnect Current request), or of one DataItem. The response is a list of Observation Collections, one for each DataItem:
[
{
"dataItemId": "Xact",
"sampleValue": [
{ "result": 125.43, "timestamp": "2026-10-08T14:30:05.1234567Z", "sequence": 102345 }
]
},
{
"dataItemId": "execution",
"eventValue": [
{ "result": "ACTIVE", "timestamp": "2026-10-08T14:29:58.0000000Z", "sequence": 102301 }
]
},
{
"dataItemId": "system",
"condition": [
{ "level": "NORMAL", "timestamp": "2026-10-08T12:00:00.0000000Z", "sequence": 1001 }
]
}
]
| List | Used For | Properties |
|---|---|---|
sampleValue | Numeric SAMPLEs (ex. positions, temperatures) | result (number), duration, resetTriggered |
eventValue | EVENTs (ex. Execution, Program, Part Count) | result (text), resetTriggered |
condition | CONDITIONs (alarms) | level (NORMAL, WARNING, FAULT, UNAVAILABLE), nativeCode, nativeSeverity, qualifier, result (the alarm message) |
Every Observation also has a timestamp, the Agent's instanceId and sequence, and isUnavailable when the value is UNAVAILABLE.
To read only some DataItems, send their IDs as a JSON array in a POST request (up to 500 IDs):
POST collection/data/devices/{deviceUuid}/observations
Content-Type: application/json
["execution", "partcount", "Xact"]
Historical Observations
Add a start and end to the same routes to read the Observations recorded in a time range:
GET collection/data/devices/{deviceUuid}/observations?start=1h-ago&end=now
GET collection/data/devices/{deviceUuid}/{dataItemId}/observations?start=today&end=now
| Parameter | Default | Description |
|---|---|---|
start | The start of the time range (included). See Time Parameters | |
end | The end of the time range (not included) | |
take | 1000 | The maximum number of Observations to return |
skip | 0 | The number of Observations to skip, for paging |
sortOrder | 1 | 1 for oldest first, -1 for newest first |
includeNext | false | Also return nextTimestamp, when the next Observation of the same DataItem was, which is how long each Event and Condition lasted |
Both start and end must be set. With only one of them, the current values are returned.
take and skip apply to each Category (SAMPLE, EVENT, and CONDITION) separately, so a response can have up to take Observations of each.
To read a large time range, request smaller ranges, or request the next page (skip = the number already read) until fewer than take are returned.
Filter Observations
These parameters narrow the Observations returned, current or historical:
| Parameter | Description |
|---|---|
category | Only sample, event, or condition Observations |
unavailable | true for only UNAVAILABLE values, or false to leave them out |
value, comparison, value2 | The value of a Sample or an Event, with category set. Samples compare numbers with eq, ne, gt, gte, lt, lte, or between (with value2). Events compare text with eq, ne, or contains. The default comparison is eq |
level | Conditions at these levels (comma separated, ex. WARNING,FAULT) |
nativeCode, qualifier | Conditions with this native code or qualifier (ex. HIGH) |
message | Conditions whose message contains this text |
# Every FAULT of the last day
GET collection/data/devices/{deviceUuid}/observations?start=1d-ago&end=now&level=FAULT
# How long the machine was ACTIVE today
GET collection/data/devices/{deviceUuid}/execution/observations?start=today&end=now&category=event&value=ACTIVE&includeNext=true
# Spindle loads above 80
GET collection/data/devices/{deviceUuid}/Sload/observations?start=8h-ago&end=now&category=sample&comparison=gt&value=80
Streaming Observations
New Observations of a Device can be received as they're collected, over a WebSocket:
ws://{server}:8490/api/collection/data/devices/{deviceUuid}/observations
Each message is a JSON response, with the Observation Collection Base64 encoded in content:
{
"statusCode": 200,
"contentType": "application/json",
"content": "eyJkYXRhSXRlbUlkIjoiZXhlY3V0aW9uIiwiZXZlbnRWYWx1ZSI6Wy4uLl19"
}
The stream is built on the Messages MTConnect Server publishes, so it requires the Device to have a Messages Profile using the default Base Topic
(trakhound/mtconnect/collection), with an MQTT Service reachable through the default Router. The Profile's Filter applies.
To receive Observations from another Base Topic, subscribe to the MQTT broker directly.
MTConnect Assets
| Route | Returns |
|---|---|
GET collection/assets | The latest version of each Asset, without its XML. Filter with deviceUuid, type (ex. CuttingTool), and removed=true to include removed Assets |
GET collection/assets/{deviceUuid}/{assetId} | One Asset, with the full Asset as MTConnect XML in Content |
DeviceUuid), unlike the Device and Observation responses.
Connection Status
Connection Status is kept for each collected Device by its Configuration ID (ex. c-a1b2c3, shown in the address of the Device's page in the App).
| Route | Returns |
|---|---|
GET collection/connections/status | The current status of every Device |
GET collection/connections/{configurationId}/status | The current status of one Device |
GET collection/connections/status/history | Status changes (newest first), filtered with from, to, status (comma separated), and limit (default 100, up to 10,000) |
GET collection/connections/{configurationId}/status/history | Status changes of one Device |
Status is CONNECTED, CONNECTING, DISCONNECTED, ERROR, STOPPED, or DISABLED,
Message describes an error, and Timestamp is when the status last changed. For example, the errors of the last day:
GET collection/connections/status/history?from=1d-ago&status=DISCONNECTED,ERROR
Statistics
| Route | Returns |
|---|---|
GET collection/statistics/devices | The Observations collected for each Device (Total, FirstTimestamp, LastTimestamp), and the average rates per second, minute, and hour |
GET collection/statistics/devices/{deviceUuid} | One Device |
GET collection/statistics/devices/{deviceUuid}/data-items | Each DataItem of a Device |
GET collection/statistics/retention | For each Retention rule and Device: totalDeleted, lastDeleted, ttlSeconds, lastRun, catchingUp, and lastError |
The Asset, Connection Status, and Statistics routes read from every Router used by a Tables Profile, and combine the results. Add routerId to read from a single Router.
Examples
API=http://localhost:8490/api
KEY=<your API Key>
DEVICE=OKUMA.Lathe.123456
# List the Devices
curl -H "X-API-Key: $KEY" "$API/collection/data/devices"
# Current values of a Device
curl -H "X-API-Key: $KEY" "$API/collection/data/devices/$DEVICE/observations"
# The Execution state over the last 8 hours
curl -H "X-API-Key: $KEY" "$API/collection/data/devices/$DEVICE/execution/observations?start=8h-ago&end=now"
# Current values of some DataItems
curl -X POST -H "X-API-Key: $KEY" -H "Content-Type: application/json" \
-d '["execution", "partcount"]' \
"$API/collection/data/devices/$DEVICE/observations"import requests
API = "http://localhost:8490/api"
HEADERS = {"X-API-Key": "<your API Key>"}
# Current values of each Device
for device in requests.get(f"{API}/collection/data/devices", headers=HEADERS).json():
current = requests.get(f"{API}/collection/data/devices/{device['uuid']}/observations", headers=HEADERS).json()
for collection in current:
for values in ("sampleValue", "eventValue", "condition"):
for observation in collection.get(values, []):
value = observation.get("result", observation.get("level"))
print(device["name"], collection["dataItemId"], value, observation["timestamp"])
# The part count over the last day, newest first
history = requests.get(
f"{API}/collection/data/devices/OKUMA.Lathe.123456/partcount/observations",
params={"start": "1d-ago", "end": "now", "sortOrder": -1, "take": 100},
headers=HEADERS)
if history.status_code == 200:
for observation in history.json()[0]["eventValue"]:
print(observation["timestamp"], observation["result"])// Streaming from a browser on the same origin as the App, which is already signed in
const deviceUuid = "OKUMA.Lathe.123456";
const socket = new WebSocket(`ws://localhost:8490/api/collection/data/devices/${deviceUuid}/observations`);
socket.onmessage = (event) => {
const response = JSON.parse(event.data);
if (response.statusCode !== 200) return;
const collection = JSON.parse(atob(response.content));
const observations = collection.sampleValue ?? collection.eventValue ?? collection.condition ?? [];
for (const observation of observations) {
console.log(collection.dataItemId, observation.result ?? observation.level, observation.timestamp);
}
};using System.Net.Http.Json;
using System.Text.Json;
var http = new HttpClient { BaseAddress = new Uri("http://localhost:8490/api/") };
http.DefaultRequestHeaders.Add("X-API-Key", "<your API Key>");
var devices = await http.GetFromJsonAsync<JsonElement[]>("collection/data/devices");
foreach (var device in devices)
{
var uuid = device.GetProperty("uuid").GetString();
var response = await http.PostAsJsonAsync($"collection/data/devices/{uuid}/observations", new[] { "execution" });
if (!response.IsSuccessStatusCode) continue;
var collections = await response.Content.ReadFromJsonAsync<JsonElement[]>();
var execution = collections[0].GetProperty("eventValue")[0].GetProperty("result").GetString();
Console.WriteLine($"{uuid} : {execution}");
}Other Ways to Read Data
| Method | Use When |
|---|---|
| REST API (this page) | Reading current values, history, Assets, and status on request |
| MQTT | Receiving Observations as they're collected, in any MQTT client |
| Database | Reporting and analytics tools that connect to a database directly |
| Agent Hub | MTConnect clients that read from an MTConnect Agent |