WWavac Support Manage API access
Menu
Customer API
Customer API / API reference

Aggregate data API

Query approved Friendly Tags as time-weighted series without repeating series metadata for every point.

In this article

Request

Use GET /api/customer/v1/data with a site returned by discovery.

Parameter Required Meaning
siteId Yes A site identifier returned by discovery.
lineId No Narrows the request to one line returned under the site.
machineId No Narrows the request to one machine. lineId is required when supplied.
from Yes Inclusive start of the requested interval as an RFC 3339 timestamp with offset.
to Yes Exclusive end of the interval; it must be later than from.
tagGuid No Repeat for up to 100 Friendly Tags. Use values returned by discovery.
aggregationIntervalSeconds No Positive requested bucket width through 86400 seconds. The default is 60 and the effective minimum is applied.
pageSize No Positive requested number of aggregate points. The effective maximum is applied.
cursor No Opaque nextCursor from the preceding page.

This request reads one hour of one Friendly Tag in 60-second buckets:

GET /api/customer/v1/data?siteId=site-1&lineId=line-1&machineId=machine-1&tagGuid=11111111-1111-4111-8111-111111111111&from=2026-09-01T12%3A00%3A00Z&to=2026-09-01T13%3A00%3A00Z&aggregationIntervalSeconds=60&pageSize=1000
Authorization: Bearer <access-token>
Accept: application/json

Success response

The response writes metadata once per logical series and places time-varying values in points:

{
  "aggregation": {
    "intervalSeconds": 60,
    "method": "timeWeightedLocf"
  },
  "series": [
    {
      "siteId": "site-1",
      "siteName": "Plant One",
      "lineId": "line-1",
      "lineName": "Packaging",
      "machineId": "machine-1",
      "machineName": "Case Packer",
      "deviceId": "device-1",
      "tagGuid": "11111111-1111-4111-8111-111111111111",
      "tagName": "IsRunning",
      "dataType": "Bool",
      "engineeringUnits": null,
      "category": "connection",
      "valueMeaning": "percentTimeTrue",
      "points": [
        {
          "timestamp": "2026-09-01T12:00:00Z",
          "value": 100,
          "minimum": 100,
          "maximum": 100,
          "sampleCount": 0
        }
      ]
    }
  ],
  "nextCursor": null
}

Interpret aggregate values

timeWeightedLocf carries the last known value forward and weights values by how long they apply within each bucket. A quiet signal does not disappear merely because it did not publish another observation during the bucket.

Field Meaning
aggregation.intervalSeconds Effective bucket width. Read it instead of assuming the requested width was accepted unchanged.
points[].timestamp UTC start of the aggregate bucket.
valueMeaning: timeWeightedAverage value is the time-weighted average for a numeric Friendly Tag.
valueMeaning: percentTimeTrue value is the percentage of known bucket time that a Boolean Friendly Tag was true, from 0 through 100.
minimum, maximum Lowest and highest values represented during the bucket. Boolean values use the 0-through-100 scale.
sampleCount Observations received in the bucket. Zero can still accompany a valid value carried from an earlier observation.

sampleCount is not a completeness percentage. A logical series is identified by siteId, lineId, machineId, deviceId, and tagGuid.

Paging and clamping

pageSize counts points, not series envelopes. The same logical series can appear on more than one page; merge points by series identity and timestamp.

An oversized page size is capped and reported by X-Effective-Page-Size. An aggregation interval below the permitted minimum is raised and reported by X-Effective-Aggregation-Interval-Seconds.

Follow nextCursor as described in pagination and data consistency. A null value completes the current traversal.

Errors

Malformed or conflicting parameters return 400. Authorization and policy failures return 401 or 403; rate exhaustion returns 429. See resolve Customer API errors for corrective actions.