Skip to main content

Get data history

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

Retrieve values of assigned dataStreamId for a device using cursor-based pagination for better performance.

Why Cursor-based Pagination?

  • Much faster than offset-based pagination, especially for large datasets
  • Constant performance regardless of page depth (page 1 and page 1000 have same speed)
  • No expensive OFFSET operations that skip thousands of records
  • No totalCount calculation - avoids heavy COUNT queries

How to Use:

  1. First request: Omit the cursor parameter
  2. Subsequent requests: Use nextCursor from previous response as cursor parameter
  3. Continue until hasMore is false

Parameters

  • deviceId (string, required): Unique identifier of the device. Example: 74fe488d5d35
  • dataStreamId (Guid, required): Unique ID of the data stream. Example: 3a217ee3-fb2c-617b-6ff6-7257537afade
  • start (DateTime, required): Start timestamp of the query range. Example: 2025-09-01T00:00:00Z
  • end (DateTime, required): End timestamp of the query range. Example: 2025-09-02T00:00:00Z
  • cursor (long, optional): Cursor timestamp from previous page (Unix milliseconds). Omit for first page.
  • limit (int, optional): Maximum results per page (default: 17, max: 1000).

Response Fields:

  • deviceId (string): Device unique ID the samples belong to.
  • dataStreamId (Guid): Unique ID of the data stream the samples belong to.
  • start (DateTime): Start timestamp of the queried range in ISO 8601 UTC.
  • end (DateTime): End timestamp of the queried range in ISO 8601 UTC.
  • dataType (string): Data type of the stream values (e.g. double, boolean, integer, string).
  • dataObjects (array): Timestamped values, ordered by timestamp. Each item:
    • timestamp (DateTime): Sample time in ISO 8601 UTC. Example: 2025-09-01T08:00:00Z
    • value: Sample value; its type is declared by dataType.
  • nextCursor (long): Timestamp to use for next page (null if no more data).
  • hasMore (boolean): Whether there are more pages available.

All timestamps are stored and returned in UTC. FR-14: a stream with recordToDataLake=false always returns an empty page (items: [], nextCursor: null, hasMore: false; 200), never an error.

Example Usage:

# First page
GET /orgs/77ffccee-4f7a-46cd-a000-8a2c254edb53/devices/74fe488d5d35/data-streams/3a217ee3-fb2c-617b-6ff6-7257537afade/values/historical?start=2025-01-01T00:00:00Z&end=2025-01-02T00:00:00Z&limit=100
            
# Second page (use nextCursor from first response)
GET /orgs/77ffccee-4f7a-46cd-a000-8a2c254edb53/devices/74fe488d5d35/data-streams/3a217ee3-fb2c-617b-6ff6-7257537afade/values/historical?start=2025-01-01T00:00:00Z&end=2025-01-02T00:00:00Z&cursor=1704153600000&limit=100

Responses

  • 200 OK: returns cursor-based paginated data stream values.
  • 400 Bad Request: Invalid query parameters.
  • 404 Not Found: Data stream not found.

Security

  • This API requires authentication.

Request​

Responses​

Returns cursor-based paginated data stream values.