Read bucketed telemetry history

GET

/integration/v1/organizations/{organization}/devices/{uuid}/telemetry/history

curl --request GET \
  --url 'https://api.elwids.xyz/api/integration/v1/organizations/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/devices/2489E9AD-2EE2-8E00-8EC9-32D5F69181C0/telemetry/history?parameter_uuid=2489E9AD-2EE2-8E00-8EC9-32D5F69181C0&from=2026-04-15T12%3A00%3A00Z&to=2026-04-15T12%3A00%3A00Z' \
  --header 'Authorization: Bearer <token>'

Requires: telemetry:read

Rate limits: 240 a minute per address, 60 a minute per application

Readings of one parameter selected and bucketed by receipt time, inclusive bounds, at most 31 days and max_points 10 to 1000 (default 500). Bounds are clipped to the organization’s retention and reported back. 422 for an invalid window, or (under errors.runtime) when the runtime rejects the range, for example more than 2000 resulting points; 503 when the runtime is unavailable; 504 when the range takes longer than the runtime’s limit.

Authorizations

• applicationToken

Parameters

Path Parameters

organization

required

string format: uuid

The organization UUID. A value that does not match returns 404.

uuid

required

string format: uuid

A value that does not match returns 404.

Query Parameters

max_points

integer

>= 10 <= 1000

parameter_uuid

required

string format: uuid

The parameter to read.

from

required

string format: date-time

Start of the window: RFC 3339 with seconds and Z or a ±hh:mm offset.

to

required

string format: date-time

End of the window, after from and at most 31 days later: RFC 3339 with seconds and Z or a ±hh:mm offset.

Responses

200

telemetry-history.v1.

Media typeapplication/json

telemetry-history.v1: readings bucketed by receipt time, one series per configuration, data type and unit. Empty means no observations, not zero.

object

schema_version

required

Allowed value: telemetry-history.v1

device_uuid

required

string format: uuid

parameter_uuid

required

string format: uuid

retention_days

required

integer

>= 1

from

required

The window actually read, clipped to retention; null when the clipped window is empty.

string | null format: date-time

to

required

string | null format: date-time

data

required

Array<object>

object

configuration_uuid

required

string format: uuid

unit

required

string | null

data_type

required

string

points

required

Array<object>

object

at

required

Start of the bucket, by receipt time.

string format: date-time

value

required

A reading’s value; its type follows the parameter’s data_type.

string | number | boolean | null

min

number

max

number

count

required

integer

Example

{
  "schema_version": "telemetry-history.v1",
  "device_uuid": "3f8a1c2e-5b6d-4e7f-8a9b-0c1d2e3f4a5b",
  "parameter_uuid": "6d2e3f4a-5b6c-4d7e-8f9a-0b1c2d3e4f5a",
  "retention_days": 30,
  "from": "2026-10-11T00:00:00Z",
  "to": "2026-10-12T00:00:00Z",
  "data": [
    {
      "configuration_uuid": "8e7d6c5b-4a39-4281-9f0e-1d2c3b4a5968",
      "unit": "%",
      "data_type": "number",
      "points": [
        {
          "at": "2026-10-11T00:00:00Z",
          "value": 91.2,
          "min": 90.8,
          "max": 91.5,
          "count": 12
        }
      ]
    }
  ]
}

Headers

Cache-Control

required

string

/(^|[ ,])no-store([ ,]|$)/

Responses to authenticated integration requests are never cached. The header also carries private.

Example

no-store, private

401

No valid credentials: no session (first-party API), or a missing, invalid, expired or revoked application token (integration API).

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}

403

The caller is not allowed: not a member of the organization, missing a tenant or platform permission, or (integration API) an ability not granted on both the application and the token.

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}

404

Not found: an unknown organization or resource, a resource in another organization or not granted to the application, or a malformed identifier (the route does not match).

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}

422

The input failed validation.

Media typeapplication/json

422 for input that failed validation.

object

message

required

The first error, followed by a count of the others.

string

errors

required

Messages per field, keyed by the field’s dotted path. A rejection by the device runtime appears under runtime.

object

runtime

Array<string>

key

additional properties

Array<string>

Example ^generated

{
  "message": "example",
  "errors": {
    "runtime": [
      "example"
    ]
  }
}

429

A rate limit was reached; see x-rate-limits on the operation.

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}

Headers

Retry-After

required

integer

Seconds to wait before retrying.

503

The device runtime is not configured, unavailable, or could not complete the request.

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}

504

A range read took longer than the runtime’s limit. Choose a shorter range.

Media typeapplication/json

The body of most error responses.

object

message

required

string

Example ^generated

{
  "message": "example"
}