DataStreams

Use DataStreams to identify the device data your application needs and read its values. Discover an existing stream, retain its dataStreamId, then choose a latest-value, historical or aggregate query.

This guide uses a numeric temperature stream for the value-query examples. Select a real stream from your device; its name and ID may differ. Creating a stream alone does not start data collection.

For the API examples, use your deployment's API base URL and Authorization: Bearer YOUR_ACCESS_TOKEN. Prepare the target Org ID and Device ID, and use an identity authorized for the Org and requested operation. Replace route placeholders and choose time ranges containing your recorded data.

For an application using Client Credentials, request the scope required by the read operation: data-stream.read for latest, historical and aggregated values, blob.read for blob content and metadata, or data-pack.read for a Data Pack.

Understand DataStreams and Their Sources

A definition describes the data; its values are the timestamped readings received over time. Read these fields together:

• dataStreamId: The stream's UUID, used in value queries and downstream bindings.
• dataStreamName: A name unique within the device. displayName is its human-readable label.
• dataType: The value format, such as double, boolean, data-pack or blob.
• managedBy: Whether WEDA or the user maintains the definition.
• dataSource: Read-only source information. It can be absent or null for an unbound user-managed stream.
• recordToDataLake: Whether to record values for historical and aggregate queries. This is separate from local device recording.

Management	How it is maintained	What you can change
System	Synchronized from WEDA Node or WEDA SubNode sensor capabilities.	displayName, description, unitDisplay and recordToDataLake.
User	Created explicitly for purposes such as Custom Device input or an Analyzer output.	Use supported create, update and delete operations, subject to source and dependency constraints.

dataSource.type identifies WedaNode, WedaSubNode, CustomDevice or Analyzer. Its sourceEntityId identifies the source sensor, Custom Device or Analyzer. WEDA assigns these fields; do not include them in create or update requests.

How DataStreams Are Created

Choose the preparation path for your source:

Source	Preparation
WEDA Node / WEDA SubNode	Let the device report sensor capabilities. WEDA synchronizes system-managed streams, which you can then discover.
Custom Device	Create user-managed streams, then configure the Data Source and Data Parser to map incoming values to them. Follow Custom Device Integration.
Analyzer	Prepare a user-managed output stream, then bind it in the Analyzer configuration. Follow Analyzers.

A user-created stream starts unbound. Values arrive after a source is configured and supplying data. For example, reserve temperature_adjusted for a future Analyzer output, then configure the calculation in the Analyzers guide.

Discover System-Managed DataStreams

1. Let WEDA Node connect and synchronize its capabilities, including registered SubNodes.

2. Call List DataStreams for the device whose data you need:

   GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams?managedBy=System&maxResultCount=100&skipCount=0&sorting=dataStreamName%20asc
   Authorization: Bearer YOUR_ACCESS_TOKEN

   For SubNode data, use the SubNode's Device ID. Omit managedBy for both management types, or use managedBy=User for user-managed definitions.

3. Read items and totalCount. Increase skipCount by the page size for subsequent pages. maxResultCount defaults to 10, with a maximum of 100. Match the intended stream by name and source, then retain its ID.

4. Inspect the definition with Get a DataStream:

   GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}

The list supports managedBy, sorting and pagination. It has no name-search parameter; match names within the returned pages. Sorting supports dataStreamName, displayName, description, unitDisplay, dataType, recordToDataLake and managedBy.

Check the result: You have the current stream ID, expected type and source for the intended device. A definition's presence does not confirm a recent value.

System Agent Metric Types

WEDA Node's System Agent can report these metric groups. Names are examples, not a fixed inventory for every device:

Metric type	Example data
cpu	CPU usage, load and context-switch counts
memory	Total and available memory
disk	Usage and capacity for configured mount points
network	Traffic for configured or discovered interfaces
system	System time, boot time and process information
gpu	GPU utilization, subject to supported GPU and driver availability
hwinfo	Hardware and firmware information
temperature, voltage, fanspeed	Onboard readings, subject to hardware and platform-driver availability
gpio, watchdog, thermalprotection	Hardware-feature readings, subject to platform support

Discover the actual streams and their dataType on your device. SubNodes expose sensors defined by their own applications; this System Agent inventory is specific to WEDA Node. A hardware sensor can remain defined without producing a value when required hardware or drivers are unavailable.

For reporting or local recording settings, see Telemetry Configuration.

Create and Manage DataStreams

Create a user-managed stream for a Custom Device mapping or Analyzer output:

POST /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "dataStreamName": "temperature_adjusted",
  "displayName": "Adjusted temperature",
  "description": "Output destination for temperature calibration",
  "unitDisplay": "°C",
  "dataType": "double",
  "recordToDataLake": true
}

After 201 Created, retain the returned ID. The stream is managedBy: User and initially unbound. See Create a DataStream.

• Required: dataStreamName and dataType.
• Length limits: Name 128, display name 200, description 500 and unit label 50 characters. Use a name not already taken on the device.
• Value types: Scalar types include double, integer, long, boolean and string. Use exactly data-pack for structured Data Pack records and blob for the blob-metadata workflow. The API also lists supported MIME-type values for existing binary streams.

Update selected fields with Partially Update a DataStream:

PATCH /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}
Content-Type: application/json
Authorization: Bearer YOUR_ACCESS_TOKEN

{
  "displayName": "Line 1 temperature",
  "recordToDataLake": true
}

PATCH accepts only displayName, description, unitDisplay and recordToDataLake. Omitted or null fields retain their values. Update a DataStream uses PUT for a full replacement; preserve the identity fields of a system-managed stream.

Changing unitDisplay changes a label. Use an Analyzer to convert the values themselves, such as Celsius to Fahrenheit.

Delete an unused user-managed stream with Delete a DataStream:

DELETE /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}
Authorization: Bearer YOUR_ACCESS_TOKEN

The stream must have no attached source, no Analyzer usage and no Alert Policy reference. Resolve these dependencies first. System-managed streams cannot be removed through this single-stream DELETE. 409 reports a deletion constraint; 503 can mean reference checks could not be completed.

After 204 No Content, GET returns 404 and the stream is excluded from listings. Historical values remain subject to the retention policy; deleting the definition does not leave the old ID available for history queries.

Note: DataStreams after device deletion

In v1.2, deleting a device triggers asynchronous cleanup of its associated DataStream records, including system-managed definitions. The device deletion response does not mean this cleanup has already finished.

After re-creating a device, discover its current DataStreams again. Update the IDs used by your application, Analyzers, Bridges and Alert Policies as needed. Neither reuse of an old ID nor assignment of a new ID is guaranteed. This cleanup does not itself erase historical values or stored file content, and it is separate from resetting telemetry configuration. See Manage Devices for the deletion procedure.

Check the result: Read back an updated definition, or confirm a deleted definition is unavailable. Configure and verify a source separately before expecting values in a new stream.

Read Latest Values

For WEDA Node or SubNode readings in WEDA Console, select the Org, open Devices, select the device and open Telemetry. Use the APIs below for application integration, including Custom Device data.

Scope	API
All streams with a recent value on the device	Get Latest Data: GET .../data-streams/values/latest
One selected stream	Get Latest Value: GET .../data-streams/{dataStreamId}/values/latest

For the temperature stream discovered earlier:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/values/latest
Authorization: Bearer YOUR_ACCESS_TOKEN

Illustrative response:

{
  "deviceId": "74fe488d5d54",
  "dataStreamId": "e033b4b3-36e0-4dbc-a6e4-1e77185402f4",
  "dataStreamName": "temperature",
  "dataType": "double",
  "dataObject": {
    "timestamp": "2026-10-26T08:00:00Z",
    "value": 23.5
  }
}

Check dataObject.timestamp as well as the value. The all-stream response contains dataStreams; its top-level time is response-generation time, not a sample timestamp.

Latest queries use a deployment-configured freshness window, 60 minutes by default. Streams without a qualifying value are omitted from the all-stream response. With no qualifying value, the endpoint returns 204 No Content; this does not mean the definition was deleted.

Check the result: The intended stream has the expected value format and a sample timestamp recent enough for your application.

Query Historical Values

Use Get Data History to read recorded samples:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/values/historical?start=2026-10-25T08:00:00Z&end=2026-10-25T10:00:00Z&limit=100
Authorization: Bearer YOUR_ACCESS_TOKEN

1. Choose start inclusive and end exclusive, using ISO 8601 UTC timestamps. Replace the example range with one containing your data.
2. Omit cursor on the first request. Read samples from dataObjects.
3. If hasMore is true, send the returned nextCursor as cursor, keeping the stream, range and limit unchanged. Continue until hasMore is false.

The cursor is a Unix-millisecond number; copy it unchanged. limit defaults to 17, with a maximum of 1000. This response has no totalCount.

Note: Cloud history and device recording are different

With recordToDataLake: false, historical queries return an empty page with 200, not an error. Check cloud recording and the requested range when results are empty. Local device recording and manual Data Resync are separate operations; enabling cloud recording does not itself recover earlier missing readings.

Check the result: Samples belong to the intended stream and range, and you have consumed every page your application needs.

Query Aggregated Values

Use Get Aggregated Values for a query-time summary. For hourly average and maximum temperature:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/aggregate?startTime=2026-10-25T08:00:00Z&endTime=2026-10-25T10:00:00Z&period=PT1H&function=AVG&function=MAX_VALUE
Authorization: Bearer YOUR_ACCESS_TOKEN

• startTime / endTime: Query range. These differ from the historical query's start / end.
• period: Bucket width as an ISO 8601 duration, such as PT1H for one hour.
• function: One or more functions, using repeated parameters or a comma-separated value.
• slidingStep: Optional bucket step. Omitted uses period; a supplied step must not be smaller than period.

Function group	Values	Supported data types
Numeric	SUM, AVG, EXTREME, MAX_VALUE, MIN_VALUE	double, integer, long
Universal	COUNT, FIRST_VALUE, LAST_VALUE, MAX_TIME, MIN_TIME	Any declared data type

Numeric functions on a non-numeric stream reject the whole request with 422. Reduce the range, increase bucket width or request fewer functions if the query exceeds your deployment's bucket limit.

The response groups results under values, using lower-case function names. This illustrative excerpt shows one populated bucket for each function:

{
  "values": {
    "avg": [{"timestamp": 1792915200000, "value": 23.5}],
    "max_value": [{"timestamp": 1792915200000, "value": 24.2}]
  }
}

Each timestamp is a bucket start in Unix milliseconds, here 2026-10-25T08:00:00Z. A valid query without recorded samples returns an empty result. Aggregation does not create an output DataStream; use an Analyzer for derived values needed by subsequent processing.

Check the result: Functions and bucket timestamps match the requested summary. Do not interpret an empty bucket as a measured zero.

Read Data Packs and Binary Data

These operations read existing structured records and files. Use the stored record ID or file key associated with your ingested data, in addition to Device and DataStream IDs:

Value	Purpose
dataStreamId	Identifies the stream definition.
dataPackId	Identifies one Data Pack record. It is not necessarily a UUID.
blobId	Identifies one blob metadata record.
blobKey	Identifies file content. The metadata response supplies this key and a downloadUrl.

Read a Data Pack, using a stream declared exactly dataType: data-pack:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/data-packs/{dataPackId}
Authorization: Bearer YOUR_ACCESS_TOKEN

Get a Data Pack by ID returns record, the application-defined JSON content, with dataPackId, business timestamp and storage createdAt. Another stream data type returns 422.

Read blob metadata, using a stream declared exactly dataType: blob:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/blobs/{blobId}/metadata
Authorization: Bearer YOUR_ACCESS_TOKEN

Get Blob Metadata returns blobId, blobKey, blobSize, contentType, downloadFileName, uploadedAt, metadata and downloadUrl. Another stream data type returns 422.

Download file content using the returned downloadUrl with your authorized API client, or Download Binary Data with the actual blobKey:

GET /api/v1/orgs/{orgId}/devices/{deviceId}/data-streams/{dataStreamId}/blobs/{blobKey}
Authorization: Bearer YOUR_ACCESS_TOKEN

The response is binary content. Preserve the returned URL or key, including path segments. The existing binary-download operation also serves supported MIME-type streams; the new metadata read specifically requires blob.

For input, use the source and parser setup in Custom Device Integration. Its HTTP-ingestion authentication is separate from these Org-scoped reads. An upload session ID is not a stored record ID or file key.

Check the result: The record or file matches the intended stream and stored item. An existing metadata record alone does not verify a successful content download.

Constraints and Troubleshooting

Observation	Check next
No system-managed stream appears	Confirm the correct device or SubNode ID, capability synchronization and configured sensors. Allow synchronization to finish, then list again.
Definition exists but latest value is 204	Check source reporting, the sample timestamp and required hardware or drivers.
History or aggregate result is empty	Check recordToDataLake, the range and whether values were recorded. Empty results do not establish that a device was deleted.
System-managed update or stream DELETE returns 409	Preserve system-owned identity fields. For a user-managed DELETE, resolve attached sources, Analyzer usage and Alert Policy references.
DELETE returns 503	Reference checks could not finish. Retry after the dependent service is available; this is not a completed deletion.
Old stream ID returns 404 after deleting and rebuilding a device	List current streams and inspect their sources before updating bindings. Allow asynchronous cleanup and capability synchronization to settle.
Aggregate query returns 400	Check time ordering, durations, bucket step and bucket/function count.
Aggregate or record read returns 422	Check the operation's exact data-type requirements.
File download returns 404	Check the current stream and actual blobKey or returned downloadUrl. A blobId is not the file key.
API returns 401 or 403	Check token validity, Org and authorization for the operation.

Review bindings when a device is rebuilt. Data Stream Bridge and Alert Policies use DataStream IDs; a familiar display name does not establish that an old binding still targets the intended data.