Historical import

At the end of this guide, your program sends readings that a device recorded in the past (from a data logger, a CSV export or a machine's own memory) to the Proxus historian. They are stored next to the device's live values and appear in trends, reports and the Telemetry API.

Before you start

You need:

• The device in Proxus, enabled, on a running edge gateway. Note its ID (the Oid in the REST API) and its Token (shown on the device page).
• Network access to the gateway's HTTP port, 8083 by default (Server-Port in [Service]).
• Historical import turned on. It is off in the delivered configuration; see the next section.

Turn historical import on

Set these keys, then restart the hub and the gateways:

While import is off, the endpoints answer 503.

Step 1: Send a batch

POST http://<gateway>:8083/api/v1/devices/<device ID>/historical/batches
X-IoT-Token: <device token>
Idempotency-Key: lys-packer-04-2026-10-01-0001
Content-Type: application/json

{
  "records": [
    { "key": "Temperature", "time": "2026-10-01T06:00:00.000Z", "type": "Float", "value": 24.6, "unit": "°C" },
    { "key": "Speed",       "time": "2026-10-01T06:00:00.000Z", "type": "UShort", "value": 82, "unit": "rpm" },
    { "key": "Running",     "time": "2026-10-01T06:00:00.000Z", "type": "Bool", "value": true }
  ]
}

Other fields in the body are refused. The whole body may be at most 256 KiB.

The Idempotency-Key names the batch: 8 to 128 letters, digits, -, _ or .. Sending the same key with the same body again is safe and returns the first answer. Sending the same key with a different body is refused. Use one key per batch, for example the source file name and a batch number.

Step 2: Read the answer

A new batch is answered with 202 Accepted, a repeated one with 200. The Location header points at the batch.

{
  "jobId": "5b0e6a5c-6f4e-4a0e-9a59-3f8f0f8c2d11",
  "state": "Pending",
  "results": [
    { "index": 0, "state": "Pending" },
    { "index": 1, "state": "Pending" },
    { "index": 2, "state": "Rejected", "error": "InvalidTypeOrValue" }
  ],
  "storageDataset": "DeviceRawData"
}

Each record has its own result, in the order you sent them. Rejected records are not stored; the others are.

Step 3: Follow the batch

GET http://<gateway>:8083/api/v1/devices/<device ID>/historical/batches/<jobId>
X-IoT-Token: <device token>

Record states after writing: Stored, Duplicate (the same value for that tag and time is already stored), Rejected or Uncertain.

Answers without a batch

Example in Python

import time
import requests

GATEWAY = "http://localhost:8083"
DEVICE_ID = 69
DEVICE_TOKEN = "<the device's token>"


def send_batch(key, records):
    while True:
        response = requests.post(
            f"{GATEWAY}/api/v1/devices/{DEVICE_ID}/historical/batches",
            json={"records": records},
            headers={"X-IoT-Token": DEVICE_TOKEN, "Idempotency-Key": key},
            timeout=30,
        )
        if response.status_code in (429, 503):
            time.sleep(int(response.headers.get("Retry-After", "5")))
            continue
        response.raise_for_status()
        return response.json()


batch = [
    {"key": "Temperature", "time": "2026-10-01T06:00:00.000Z", "type": "Float", "value": 24.6, "unit": "°C"},
    {"key": "Temperature", "time": "2026-10-01T06:01:00.000Z", "type": "Float", "value": 24.9, "unit": "°C"},
]
job = send_batch("lys-packer-04-2026-10-01-0001", batch)
print(job["state"], [r["state"] for r in job["results"]])

What's next

• Telemetry API: check what was imported.
• Trend Workspace: see the imported values next to live ones.
• Network ports and endpoints.