# REST API

> Read collected Devices, current and historical Observations, Assets, and Connection Status from other applications.

URL: https://www.trakhound.com/docs/mtconnect-server/api

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](https://www.trakhound.com/docs/trakhound-framework/security).

### What Can Be Read

The data API reads what Collection has stored in its [Tables](https://www.trakhound.com/docs/mtconnect-server/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 `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:

| 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` |

```json
[
  {
    "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:

```json
[
  {
    "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](https://www.trakhound.com/docs/mtconnect-server/api#time) |
| `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.

> Observations are only kept as long as the Profile's [Data Retention](https://www.trakhound.com/docs/mtconnect-server/data-retention) rules allow.

### 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`:

```json
{
  "statusCode": 200,
  "contentType": "application/json",
  "content": "eyJkYXRhSXRlbUlkIjoiZXhlY3V0aW9uIiwiZXZlbnRWYWx1ZSI6Wy4uLl19"
}
```

The stream is built on the [Messages](https://www.trakhound.com/docs/mtconnect-server/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` |

> 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).

| 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

**cURL:**

```bash
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"
```

**Python:**

```python
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"])
```

**JavaScript:**

```javascript
// 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);
    }
};
```

**C#:**

```csharp
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](https://www.trakhound.com/docs/mtconnect-server/messages)** | Receiving Observations as they're collected, in any MQTT client |
| **[Database](https://www.trakhound.com/docs/mtconnect-server/tables)** | Reporting and analytics tools that connect to a database directly |
| **[Agent Hub](https://www.trakhound.com/docs/mtconnect-server/agent-hub)** | MTConnect clients that read from an MTConnect Agent |
