REST API

Read collected Devices, current and historical Observations, Assets, and Connection Status from other applications.
MTConnect Server Docs Menu

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
  • 8490 is the default port. Use the HTTP Port entered when MTConnect Server was installed.
  • /api is 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.

RouteData
collection/data/devicesDevices, Device models, Components, DataItems, and Observations (current and historical)
collection/assetsMTConnect Assets (ex. Cutting Tools)
collection/connectionsThe Connection Status of each Device, and its history
collection/statisticsObservation and Data Retention statistics

Requests and Responses

  • Requests are GET requests (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 returns 400.
  • Properties with a default value (false, 0, or null) are left out of responses. For example, isUnavailable only appears when it's true.
  • 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:

FormatExample
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 timenow, today, yesterday, this-week, last-month
A duration ago (s, m, h, d, y)30m-ago, 1h-ago, 7d-ago

Devices

RouteReturns
GET collection/data/devicesThe collected Devices, with each one's uuid, id, name, and mtconnectVersion
GET collection/data/devices/{deviceUuid}One Device
GET collection/data/devices/{deviceUuid}/modelThe full Device model (the same information as an MTConnect Probe), as a tree of Components and DataItems
GET collection/data/devices/{deviceUuid}/componentsA flat list of the Components
GET collection/data/devices/{deviceUuid}/dataitemsA 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 }
    ]
  }
]
ListUsed ForProperties
sampleValueNumeric SAMPLEs (ex. positions, temperatures)result (number), duration, resetTriggered
eventValueEVENTs (ex. Execution, Program, Part Count)result (text), resetTriggered
conditionCONDITIONs (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
ParameterDefaultDescription
startThe start of the time range (included). See Time Parameters
endThe end of the time range (not included)
take1000The maximum number of Observations to return
skip0The number of Observations to skip, for paging
sortOrder11 for oldest first, -1 for newest first
includeNextfalseAlso 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.

Observations are only kept as long as the Profile's Data Retention rules allow.

Filter Observations

These parameters narrow the Observations returned, current or historical:

ParameterDescription
categoryOnly sample, event, or condition Observations
unavailabletrue for only UNAVAILABLE values, or false to leave them out
value, comparison, value2The 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
levelConditions at these levels (comma separated, ex. WARNING,FAULT)
nativeCode, qualifierConditions with this native code or qualifier (ex. HIGH)
messageConditions 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

RouteReturns
GET collection/assetsThe 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
The Asset, Connection Status, and Statistics responses use PascalCase property names (ex. 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).

RouteReturns
GET collection/connections/statusThe current status of every Device
GET collection/connections/{configurationId}/statusThe current status of one Device
GET collection/connections/status/historyStatus changes (newest first), filtered with from, to, status (comma separated), and limit (default 100, up to 10,000)
GET collection/connections/{configurationId}/status/historyStatus 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

RouteReturns
GET collection/statistics/devicesThe 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-itemsEach DataItem of a Device
GET collection/statistics/retentionFor 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

MethodUse When
REST API (this page)Reading current values, history, Assets, and status on request
MQTTReceiving Observations as they're collected, in any MQTT client
DatabaseReporting and analytics tools that connect to a database directly
Agent HubMTConnect clients that read from an MTConnect Agent