Rune Labs Stream API

The Stream API is an HTTP API that allows clients to query data streams for a given patient.

It exposes endpoints for every type of data stream that can be queried (e.g. local field potentials, accelerometry, events, etc). Each endpoint is documented in detail, below.

Overview

Key Concepts

Throughout this document, the following terminology is used:

  • Patient refers to the user of a patient-facing app.
  • Client refers to the patient-facing app itself. A client accesses data programmatically, on behalf of a patient.
  • Device refers to the sensor serving as the datasource, such as a patient implant, phone, or wearable.

A client is associated with exactly one patient. Patients may have multiple clients, depending on how many apps are sending or accessing data. Patients and clients are resources in the Rune platform with unique identifiers, and they are used to control access to patient data.

Authentication

Authentication is required for all API requests. There are several authentication methods:

  • Access tokens (recommended)
  • Client keys

Both the access tokens and the client keys are comprised of two parts: a key ID and an access key. These are analagous to a username and password. Usage is described in detail below.

Access Tokens

Access tokens provide read access to all the patients in your organization. This is the recommended authentication method for the Stream API.

To use an access token for authentication, the HTTP request must include two headers:

  • X-Rune-User-Access-Token-Id - access token ID
  • X-Rune-User-Access-Token-Secret - access token secret

It is highly recommended that you "rotate" user access tokens every 3-6 months, by creating a new token and deactivating the old one. Store your access tokens securely, and do not share them.

Create a New Access Token

  1. Log in to the Rune web app
  2. Click on the profile icon in the top right corner.
  3. Click on User Settings.
  4. On the left sidebar, click on Access Tokens.
  5. Click CREATE ACCESS TOKEN.
  6. Copy the token ID and the token secret before closing the page. The secret will never be shown again.

Client Keys

Client keys provide read and write access to one patient.

To use a client key pair for authentication, the HTTP request must include two headers:

  • X-Rune-Client-Key-Id - client key ID
  • X-Rune-Client-Access-Key - client access key (secret)

Note that each client may only fetch data for its associated patient.

Register a New Client

  1. Log in to the Rune web app as an admin user.
  2. Find the patient you want to access data for, and open Patient Settings.
  3. Open the Clients section.
  4. Create a new client. You can name it anything, though typically it is named after your app.
  5. A default client key pair will be created with the new client. Copy the key ID and the access key before closing the page. The access key will never be shown again.

Create New Client Keys

You can create any number of client keys for a given client, through the Rune web app. If you forget a key, you can always create a new key pair and disable the old.

It is highly recommended that you "rotate" keys for a patient every 3-6 months, by creating a new client key, configuring it in the client (e.g. the patient's app), then disabling the old key. You should do this immediately if you believe the key may have been compromised (e.g. stolen from the device, posted over any insecure/public communication channel, etc).

Response Format

Endpoint URLs ending in .json return JSON-formatted data. All resources support this data format. Endpoint URLs ending in .csv return CSV data. Some resources support this data format.

Errors

Standard HTTP status codes are used to indicate success or failure. In the event of most errors, the response body is JSON that includes additional information, 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 may be returned from a single API request. 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.

A custom header field is used to paginate query results. 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 next_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.

The maximum amount of data that is returned in a single request can be specified via the page_size parameter. The default page size is different for JSON and CSV endpoints (see endpoint documentation for details). Clients should be careful about managing their memory usage, as responses may contain a large volume of data.

Acceleration

Query accelerometry data for any device that records it. Acceleration values are always in units of Gs (9.8 m/s^2).

Acceleration (JSON)

A successful request returns a JSON object, with a result key containing timeseries data. The format of the result depends on several query parameters:

  • expression determines the structure of the result object.
  • timestamp determines the format of the timestamps.
  • partition_size segments each array into sub-arrays.

See details for each query parameter, as well as the response examples.

query Parameters
patient_id
required
string

Patient ID. If authenticating with a client key pair, this parameter may be omitted: the patient is inferred from the key pair.

device_id
required
string

ID of the device from which data was reported.

start_time
required
float

Unix timestamp with the start of the time range to query. This is inclusive: all returned timestamps will be >= start_time.

end_time
required
float

Unix timestamp with the end of the time range to query. This is exclusive: all returned timestamps will be < end_time.

algorithm
string
Example: algorithm=example-dbs-v2

ID of algorithm used to generate the stream. Can be generally omitted unless known. In some cases, we'll publish an improved algorithm (e.g. a increase in timestamp accuracy), and data will be available in both the new and old version for compatibility.

expression
string
Default: "accel"

Determines what kind of accelerometry data is returned.

  • accel - return the net acceleration. This may or may not include gravity, depending on the device type.

  • user - return just the user acceleration, i.e. acceleration of device without the gravitational component. Not available for all device types.

  • gravity - return just acceleration due to gravity. Not available for all device types.

  • availability(accel) - return the availability of acceleration data: 1 if available, 0 otherwise. Defaults to 5min resolution, unless resolution or frequency are specified.

For the following expressions, resolution or frequency must be specified.

  • first(accel|user|gravity) - first acceleration value from each downsampled time interval.
  • last(accel|user|gravity) - last acceleration value from each downsampled time interval.
  • mean(accel|user|gravity) - mean acceleration value over each downsampled time interval.
  • median(accel|user|gravity) - median acceleration value over each downsampled time interval.
frequency
float

The time frequency (in Hz) of the returned timeseries. This is the reciprocal of the resolution parameter. At most one of frequency or resolution may be provided.

resolution
float

Time interval between returned points, in seconds. This is the reciprocal of the frequency parameter. At most one of frequency or resolution may be provided.

interpolation
string
Default: ""
Enum: "" "linear" null "previous" "zero"

How to fill in timestamps with no data, when frequency or resolution has been specified.

  • If this parameter is omitted or an empty string, timestamps with no data are skipped.
  • If linear, missing values are interpolated with a linear function connecting the last known value and the next.
  • If null, missing values are null.
  • If previous, missing values are filled in by repeating the last known value, until there is data again.
  • If zero, missing values are replaced with 0.0.
timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

timezone
integer
Default: 0

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.

next_page_token
string <byte>

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.

page
integer >= 0
Default: 0

(Deprecated. Use next_page_token instead)

The page number, to be used if the query result exceeds the pagination limit. Numbering starts at 0 (i.e. page=0 returns the first page of the response).

page_size
integer [ 0 .. 10000 ]
Default: 10000

Maximum number of events to return per page. If page_size=0, the default will be used.

partition_size
integer

If set, break up result data for each stream into subsets of partition_size number of points. The last partition returned may not necessarily contain partition_size points.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

429

Client IP throttled

500

Internal server error

503

Service unavailable

get /v1/accel.json
https://stream.runelabs.io/v1/accel.json

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "success": true,
  • "result":
    {
    }
}

Acceleration (CSV)

A successful request returns CSV data. The format depends on several query parameters:

  • expression determines the columns of data that are returned.
  • timestamp determines the format of the timestamps.

See details for each query parameter, as well as the response examples.

query Parameters
patient_id
required
string

Patient ID. If authenticating with a client key pair, this parameter may be omitted: the patient is inferred from the key pair.

device_id
required
string

ID of the device from which data was reported.

start_time
required
float

Unix timestamp with the start of the time range to query. This is inclusive: all returned timestamps will be >= start_time.

end_time
required
float

Unix timestamp with the end of the time range to query. This is exclusive: all returned timestamps will be < end_time.

algorithm
string
Example: algorithm=example-dbs-v2

ID of algorithm used to generate the stream. Can be generally omitted unless known. In some cases, we'll publish an improved algorithm (e.g. a increase in timestamp accuracy), and data will be available in both the new and old version for compatibility.

expression
string
Default: "accel"

Determines what kind of accelerometry data is returned.

  • accel - return the net acceleration. This may or may not include gravity, depending on the device type.

  • user - return just the user acceleration, i.e. acceleration of device without the gravitational component. Not available for all device types.

  • gravity - return just acceleration due to gravity. Not available for all device types.

  • availability(accel) - return the availability of acceleration data: 1 if available, 0 otherwise. Defaults to 5min resolution, unless resolution or frequency are specified.

For the following expressions, resolution or frequency must be specified.

  • first(accel|user|gravity) - first acceleration value from each downsampled time interval.
  • last(accel|user|gravity) - last acceleration value from each downsampled time interval.
  • mean(accel|user|gravity) - mean acceleration value over each downsampled time interval.
  • median(accel|user|gravity) - median acceleration value over each downsampled time interval.
frequency
float

The time frequency (in Hz) of the returned timeseries. This is the reciprocal of the resolution parameter. At most one of frequency or resolution may be provided.

resolution
float

Time interval between returned points, in seconds. This is the reciprocal of the frequency parameter. At most one of frequency or resolution may be provided.

interpolation
string
Default: ""
Enum: "" "linear" null "previous" "zero"

How to fill in timestamps with no data, when frequency or resolution has been specified.

  • If this parameter is omitted or an empty string, timestamps with no data are skipped.
  • If linear, missing values are interpolated with a linear function connecting the last known value and the next.
  • If null, missing values are null.
  • If previous, missing values are filled in by repeating the last known value, until there is data again.
  • If zero, missing values are replaced with 0.0.
timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

timezone
integer
Default: 0

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.

next_page_token
string <byte>

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.

page
integer >= 0
Default: 0

(Deprecated. Use next_page_token instead)

The page number, to be used if the query result exceeds the pagination limit. Numbering starts at 0 (i.e. page=0 returns the first page of the response).

page_size
integer [ 0 .. 3600000 ]
Default: 3600000

Maximum number of events to return per page. If page_size=0, the default will be used.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

429

Client IP throttled

500

Internal server error

503

Service unavailable

get /v1/accel.csv
https://stream.runelabs.io/v1/accel.csv

Response samples

Content type
text/csv
Example
Copy
time,x,y,z
1565304080.1,0,0.1,0.1
1565304080.2,1.4,0.3,0.7
1565304080.3,1,1.2,0.2

Band Power

Query band power data that is calculated on-device. This data is distinct from data that is available from the band_power(spectrogram(lfp)) expression of the LFP endpoint, which is calculated by Rune Labs.

Band Power (JSON)

A successful request returns a JSON object, with a result key containing timeseries data. The format of the result depends on several query parameters:

  • expression determines the structure of the result object.
  • timestamp determines the format of the timestamps.
  • partition_size segments each array into sub-arrays.

See details for each query parameter, as well as the response examples.

query Parameters
patient_id
required
string

Patient ID. If authenticating with a client key pair, this parameter may be omitted: the patient is inferred from the key pair.

device_id
required
string

ID of the device from which data was reported.

start_time
required
float

Unix timestamp with the start of the time range to query. This is inclusive: all returned timestamps will be >= start_time.

end_time
required
float

Unix timestamp with the end of the time range to query. This is exclusive: all returned timestamps will be < end_time.

algorithm
string
Example: algorithm=example-dbs-v2

ID of algorithm used to generate the stream. Can be generally omitted unless known. In some cases, we'll publish an improved algorithm (e.g. a increase in timestamp accuracy), and data will be available in both the new and old version for compatibility.

anatomy
string
Example: anatomy=GPi,STN,M1

CSV of the target anatom(y|ies) where the device is attached or implanted. Only applies to multi-sensor devices. Can be omitted to return data from all sensors across any anatomy.

band
string
Example: band=16.4hz-19.8hz,8.5hz-9.6hz

CSV of the band power ranges to return data for.

channel
string
Example: channel=0,1,2,3

CSV of the device channels to return data for. Only applies to multi-sensor devices.

sensor
string
Example: sensor=0-2,5-6

CSV of the device sensors (e.g. electrode pair) to return data for. Only applies to multi-sensor devices.

expression
string
Default: "power"
Enum: "power" "availability(power)"

Determines what kind of data is returned.

  • power - return power data.
  • availability(power) - return the availability of power data: 1 if available, 0 otherwise. Defaults to 5min resolution, unless resolution or frequency are specified.
frequency
float

The time frequency (in Hz) of the returned timeseries. This is the reciprocal of the resolution parameter. At most one of frequency or resolution may be provided.

resolution
float

Time interval between returned points, in seconds. This is the reciprocal of the frequency parameter. At most one of frequency or resolution may be provided.

interpolation
string
Default: ""
Enum: "" "linear" null "previous" "zero"

How to fill in timestamps with no data, when frequency or resolution has been specified.

  • If this parameter is omitted or an empty string, timestamps with no data are skipped.
  • If linear, missing values are interpolated with a linear function connecting the last known value and the next.
  • If null, missing values are null.
  • If previous, missing values are filled in by repeating the last known value, until there is data again.
  • If zero, missing values are replaced with 0.0.
timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

timezone
integer
Default: 0

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.

next_page_token
string <byte>

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.

page
integer >= 0
Default: 0

(Deprecated. Use next_page_token instead)

The page number, to be used if the query result exceeds the pagination limit. Numbering starts at 0 (i.e. page=0 returns the first page of the response).

page_size
integer [ 0 .. 10000 ]
Default: 10000

Maximum number of events to return per page. If page_size=0, the default will be used.

partition_size
integer

If set, break up result data for each stream into subsets of partition_size number of points. The last partition returned may not necessarily contain partition_size points.

filename
string

If provided, causes the endpoint to return a response with an attachment content disposition. Used to trigger a file download in browsers.

Responses

200

Successful request

400

Bad request

401

Not authorized to perform the request

404

Not found

429

Client IP throttled

500

Internal server error

503

Service unavailable

get /v1/band_power.json
https://stream.runelabs.io/v1/band_power.json

Response samples

Content type
application/json
Example
Copy
Expand all Collapse all
{
  • "success": true,
  • "result":
    {
    }
}

Band Power (CSV)

A successful request returns CSV data. The format depends on several query parameters:

  • expression determines the columns of data that are returned.
  • timestamp determines the format of the timestamps.

See details for each query parameter, as well as the response examples.

query Parameters
patient_id
required
string

Patient ID. If authenticating with a client key pair, this parameter may be omitted: the patient is inferred from the key pair.

device_id
required
string

ID of the device from which data was reported.

start_time
required
float

Unix timestamp with the start of the time range to query. This is inclusive: all returned timestamps will be >= start_time.

end_time
required
float

Unix timestamp with the end of the time range to query. This is exclusive: all returned timestamps will be < end_time.

algorithm
string
Example: algorithm=example-dbs-v2

ID of algorithm used to generate the stream. Can be generally omitted unless known. In some cases, we'll publish an improved algorithm (e.g. a increase in timestamp accuracy), and data will be available in both the new and old version for compatibility.

anatomy
string
Example: anatomy=GPi,STN,M1

CSV of the target anatom(y|ies) where the device is attached or implanted. Only applies to multi-sensor devices. Can be omitted to return data from all sensors across any anatomy.

band
string
Example: band=16.4hz-19.8hz,8.5hz-9.6hz

CSV of the band power ranges to return data for.

channel
string
Example: channel=0,1,2,3

CSV of the device channels to return data for. Only applies to multi-sensor devices.

sensor
string
Example: sensor=0-2,5-6

CSV of the device sensors (e.g. electrode pair) to return data for. Only applies to multi-sensor devices.

expression
string
Default: "power"
Enum: "power" "availability(power)"

Determines what kind of data is returned.

  • power - return power data.
  • availability(power) - return the availability of power data: 1 if available, 0 otherwise. Defaults to 5min resolution, unless resolution or frequency are specified.
frequency
float

The time frequency (in Hz) of the returned timeseries. This is the reciprocal of the resolution parameter. At most one of frequency or resolution may be provided.

resolution
float

Time interval between returned points, in seconds. This is the reciprocal of the frequency parameter. At most one of frequency or resolution may be provided.

interpolation
string
Default: ""
Enum: "" "linear" null "previous" "zero"

How to fill in timestamps with no data, when frequency or resolution has been specified.

  • If this parameter is omitted or an empty string, timestamps with no data are skipped.
  • If linear, missing values are interpolated with a linear function connecting the last known value and the next.
  • If null, missing values are null.
  • If previous, missing values are filled in by repeating the last known value, until there is data again.
  • If zero, missing values are replaced with 0.0.
timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

timezone
integer
Default: 0

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.

next_page_token
string <byte>

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-