Rune Labs V2 Stream API

Rune Labs V2 Stream API

An HTTP API to query timeseries data.

Overview

V1 vs V2

Like the V1 Stream API, the V2 API can be used to query timeseries which are derived from data uploaded to the Rune Platform. However, V2 introduces new concepts that streamline how data is organized, stored, and accessed. While the data from both APIs is derived from the same uploaded datasets, the underlying storage is entirely independent.

Definitions

Patient

The person about whom data was measured. This may include a StrivePD user, a person with a neural implant, etc. Each patient has a unique identifier ("patient ID"). Patient IDs are generated by Rune and cannot be changed.

Device

The sensor serving as the data source (e.g. a DBS implant, iOS application, wearable device, etc.). A patient may have multiple devices: each one has a unique identifier ("device ID"). Device IDs are generated by Rune and cannot be changed. They do not correspond to any identifier or information from the device itself.

Stream

A single timeseries, defined by a stream type and a unique combination of parameters (key/value pairs). Each stream has a unique identifier ("stream ID").

To access data from this API, you must know which stream IDs you're interested in querying. Use Rune's GraphQL API to discover the stream IDs that are available to you.

Stream Type

A categorization of streams, both semantically and structurally. Roughly speaking, it represents the physical quantity being measured (voltage, acceleration, etc), including the unit of measurement. It also describes the shape of the stream’s data, as one or more dimensions. Think of a dimension as a column in a table, where each value in the timeseries is a row. Stream type definitions also include human-readable labels and descriptions.

Algorithm

A label associated with each stream, which describes how data was processed to produce the stream values (including how it is parameterized). Each algorithm label is formatted as algorithm-name.version (e.g. ingest-strive-applewatch-motion.0).

The term "algorithm" does not necessarily imply meaningful data manipulation or calculations (though it can). For example, the ingest-strive-applewatch-motion algorithm simply ingests the raw accelerometry data that is recorded on an Apple Watch and uploaded by the Strive iOS application.

Stream Parameters

Key/value pairs that are used to label streams.

All streams are labeled with the following:

Streams may also have any number of parameters, with other key/value pairs. By convention, all of our streams include the following parameters:

For details about how streams are parameterized, refer to the documentation for a particular algorithm.

Authentication

Authentication is required for all API requests. The V2 API uses the same authentication mechanisms as V1: see the V1 API documentation for details.

Errors

Standard HTTP status codes are used to indicate success or failure. In the event of most errors, the response body is JSON, with the following format:

{
  "success": false,
  "error": {
    "message": "Human-readable error description",
    "type": "EnumeratedErrorKind"
  }
}

Pagination

There is a limit on the amount of data that is returned in a response. This page size is determined by the server. If the queried time range contains more than one page’s worth of data, you must make multiple API requests to fetch the complete result.

If an API response includes a X-Rune-Next-Page-Token header, make another request to fetch the next page of data. In the next request, provide the value of this header in the page_token query parameter. Keep the rest of the query parameters identical. When the end of pagination has been reached, the X-Rune-Next-Page-Token header field will not exist in the response.

Each pagination token is valid for 5 minutes.

Single Stream

Fetch data for a single stream by its stream ID.

Stream Data

A successful request returns data from a single stream. The response format is determined largely by the stream type of the data: CSV columns (or JSON keys) are named for the dimensions of the corresponding stream type.

There is always a column/key that contains the duration of each measurement in the timeseries (in nanoseconds): "measurement_duration_ns". The duration value is extracted from the device data, with the following order of precedence:

path Parameters
stream_id
required		 string
Example: a1379454321e63222f547d8f929a2451d0f295cfbd77fabf9ce8090e1c31c571
Unique ID for a Stream.
query Parameters
start_time float
Unix timestamp (in seconds, with optional fraction) of the start of the
time range to query. This is an inclusive boundary (>= start_time).
It is invalid to specify both start_time and start_time_ns.
start_time_ns int
The same as start_time, but expressed as integer nanoseconds.
It is invalid to specify both start_time and start_time_ns.
end_time float
Unix timestamp (in seconds, with optional fraction) of the end of the
time range to query. This is an exclusive boundary (< end_time).
It is invalid to specify both end_time and end_time_ns.
end_time_ns int
The same as end_time, but expressed as integer nanoseconds.
It is invalid to specify both end_time and end_time_ns.
format string
Default: "csv"
Enum:"json""csv"
Determines the content type of the response.
limit int
The maximum number of timestamps to return, across all pages of the
response.
page_token string
A token provided in the request to obtain the subsequent page of
records in a dataset. The value is obtained from the
X-Rune-Next-Page-Token response header field. See Pagination
for details.
timestamp string
Default: "unix"
Enum:"unix""unixns""iso"
Determines how timestamps are formatted in the response:
- unix - Unix seconds, with up to 7 fractional digit precision.
- unixns - Unix nanoseconds (integer).
- iso - Formatted as RFC3339, including the timezone offset.
timezone integer
Default: 0
Example: timezone=-28800
The timezone offset, in seconds, used to calculate string-based
timestamp formats such as datetime and iso. For example,
PST (UTC-0800) is represented as -28800. If omitted, the
timezone is UTC.
timezone_name string
Default: ""
Example: timezone_name=America/Los_Angeles
The name from the IANA timezone database used to calculate string-based
timestamp formats such as datetime and iso. For example,
America/Los_Angeles. While timezone uses a fixed offset,
timezone_name will return the correct UTC offset for a
given date/time in order to account for daylight saving time.
If omitted, the timezone is UTC unless a timezone parameter
is provided. If both a timezone and a timezone_name are provided
the request will return an error. If timezone_name is provided, aggregate
queries with resolution equivalent to multiples of a day (86400 seconds)
will group result windows by calendar day(s) in the provided timezone.
translate_enums string
Default: false
Enum:truefalse
When fetching a stream that includes an enum data type, this determines
whether to translate enums into their string representation. By default,
enums are returned as integer values.
All possible enum values for a given stream can be queried from the
GraphQL API, as part of the stream metadata.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

500

Internal server error

get/streams/{stream_id}

https://stream.runelabs.io/v2/streams/{stream_id}

Response samples

Stream Availability

Returns a boolean timeseries, indicating whether stream data exists in a given window of time. The resolution parameter determines the granularity of this timeseries (i.e. the interval between each timestamp in the series). The timeseries is aligned such that each timestamp (as Unix seconds), is evenly divisible by the resolution. If the requested start_time is not evenly divisible by the resolution, the query range is extended to the nearest preceding aligned time. If the end_time is not evenly divisible by the resolution, the query range is extended to the nearest following aligned time. This ensures that the returned timestamps are evenly spaced and that each one represents a duration of time equal to the resolution (rather than getting truncated).

path Parameters
stream_id
required		 string
Example: a1379454321e63222f547d8f929a2451d0f295cfbd77fabf9ce8090e1c31c571
Unique ID for a Stream.
query Parameters
start_time
required		 float
Unix timestamp (in seconds, with optional fraction) of the start of the
time range to query. This is an inclusive boundary (>= start_time).
end_time
required		 float
Unix timestamp (in seconds, with optional fraction) of the end of the
time range to query. This is an exclusive boundary (< end_time).
resolution
required		 integer [ 300 .. 86400 ]
Interval between returned timestamps, in seconds.
format string
Default: "csv"
Enum:"json""csv"
Determines the content type of the response.
limit int
The maximum number of timestamps to return, across all pages of the
response.
page_token string
A token provided in the request to obtain the subsequent page of
records in a dataset. The value is obtained from the
X-Rune-Next-Page-Token response header field. See Pagination
for details.
timestamp string
Default: "unix"
Enum:"unix""unixns""iso"
Determines how timestamps are formatted in the response:
- unix - Unix seconds, with up to 7 fractional digit precision.
- unixns - Unix nanoseconds (integer).
- iso - Formatted as RFC3339, including the timezone offset.
timezone integer
Default: 0
Example: timezone=-28800
The timezone offset, in seconds, used to calculate string-based
timestamp formats such as datetime and iso. For example,
PST (UTC-0800) is represented as -28800. If omitted, the
timezone is UTC.
timezone_name string
Default: ""
Example: timezone_name=America/Los_Angeles
The name from the IANA timezone database used to calculate string-based
timestamp formats such as datetime and iso. For example,
America/Los_Angeles. While timezone uses a fixed offset,
timezone_name will return the correct UTC offset for a
given date/time in order to account for daylight saving time.
If omitted, the timezone is UTC unless a timezone parameter
is provided. If both a timezone and a timezone_name are provided
the request will return an error. If timezone_name is provided, aggregate
queries with resolution equivalent to multiples of a day (86400 seconds)
will group result windows by calendar day(s) in the provided timezone.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

500

Internal server error

get/streams/{stream_id}/availability

https://stream.runelabs.io/v2/streams/{stream_id}/availability

Response samples

Daily Aggregate

Returns an average aggregated day divided into intervals. This endpoint is useful for powering visualizations that highlight daily patterns based on time of day.

Daily aggregates are only supported for stream types with two dimensions (i.e. a timestamp and a numeric value).

To calculate a daily aggregate, all data points within n_days from start_time are considered. Each data point is grouped together into intervals by rounding down the time portion of the timestamp to the nearest resolution seconds. Then, the mean is calculated from the data points in each interval to arrive at an aggregate value.

If no data points appeared within an interval for any of the days being aggregated, a null is returned.

path Parameters
stream_id
required		 string
Example: a1379454321e63222f547d8f929a2451d0f295cfbd77fabf9ce8090e1c31c571
Unique ID for a Stream.
query Parameters
start_time
required		 float
Unix timestamp (in seconds, with optional fraction) of the start of the
time range to query. This is an inclusive boundary;
resolution
required		 int [ 60 .. 86400 ]
Length of time (in seconds) for the window used to calculate intervals.
Must evenly divide into a 24 hour period.
n_days
required		 int [ 1 .. 14 ]
Number of days across which to compute daily aggregate.
Each day is a 24 hour period beginning from the start_time.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

500

Internal server error

This cleaned content preserves all relevant details while eliminating unnecessary navigation and advertisement elements.