# Rune Labs V2 Stream API
An HTTP API to query timeseries data.
## Overview
### V1 vs V2
Like the [V1 Stream API](https://docs.runelabs.io/stream/v1), the V2 API can
be used to query timeseries which are derived from data uploaded to the
Rune Platform. However, V2 introduces new [concepts](https://docs.runelabs.io/#section/Overview/Definitions)
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](https://www.strive.group/) 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:
- `patient_id` — the anonymized ID of the person whose data this is.
- `device_id` — the device from which the stream was recorded.
- `algorithm` — describes how data was processed to produce the stream
(see "Algorithm" definition).
Streams may _also_ have any number of parameters, with other key/value pairs.
By convention, all of our streams include the following parameters:
- `category`– a broad categorization of the data type.
- E.g. `neural`, `vital_sign`, etc
- `measurement`– a specific label for what is being measured
- E.g. `heart_rate`, `step_count`, etc
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](https://docs.runelabs.io/stream/v1/#section/Overview/Authentication)
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:
- Some devices specify a start and end time for each measured value.
Whenever this is the case, the **start time** of each interval is
used as the timestamp for each observation in the timeseries,
and the duration is `end_time – start_time`.
- Other devices specify a **sampling rate** for a particular
measurement. When this is the case (and the true duration is
unknown), the duration of each observation is set to `1/sample rate`.
- Otherwise, the duration is `0` (which indicates that it is unknown).
##### 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](https://docs.runelabs.io/#section/Overview/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
- 200
- 400
- 401
- 404
- 500
### 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](https://docs.runelabs.io/#section/Overview/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
- 200
- 400
- 401
- 404
- 500
### 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.