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. For accel, user, and gravity expressions the default minimum resolution is 0.01 seconds, unless resolution or frequency are specified.

  • 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 the minimum resolution of 5 min, 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
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.

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

Response samples

Content type
application/json
Example
{
  • "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. For accel, user, and gravity expressions the default minimum resolution is 0.01 seconds, unless resolution or frequency are specified.

  • 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 the minimum resolution of 5 min, 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
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.

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: 2000000

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

Responses

Response samples

Content type
text/csv
Example
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. Defaults to the minimum resolution of 0.01 seconds, unless resolution or frequency are specified.
  • availability(power) - return the availability of power data: 1 if available, 0 otherwise. Defaults to the minimum resolution of 1 min, 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
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.

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

Response samples

Content type
application/json
Example
{
  • "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. Defaults to the minimum resolution of 0.01 seconds, unless resolution or frequency are specified.
  • availability(power) - return the availability of power data: 1 if available, 0 otherwise. Defaults to the minimum resolution of 1 min, 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
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.

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

Response samples

Content type
text/csv
Example
timestamp,algorithm,anatomy,band,channel,sensor,power
1590706215.314000,medtronic-percept-1,GPi,16.4hz-19.8hz,0,7-5,0.1
1590706231.971000,medtronic-percept-1,GPi,16.4hz-19.8hz,0,7-5,1.2
1590706240.604000,medtronic-percept-1,STN,16.4hz-19.8hz,0,7-5,2.3
1590706248.245000,medtronic-percept-1,STN,16.4hz-19.8hz,2,0-2,3.4
1590706257.554000,medtronic-percept-1,STN,16.4hz-19.8hz,2,0-2,-4.5

Events

There are two distinct types of event records, each of which can be queried from a dedicated endpoint:

  • Events are associated with a single point in time.
  • Spans are items that have a duration or range of time.

Unlike other streams, events and spans have no notion of sampling frequency or interpolation.

Classification

Both events and spans are categorized through a nested, three-level classification, in the form of namespace.category.enum.

  1. Namespace: the general source of the event. The most common namespace is device, which includes all events generated by patient devices. Another common namespace is patient, which includes items that were recorded by a patient. Other namespaces include (but are not limited to) custom events recorded by researchers, clinicians, or sourced from external health databases.
  2. Category: the classification of different types of events (e.g. medication, settings, therapy, etc).
  3. Enum: a specific enumeration within the category. Not all events have an enumeration. For example, within the medication category, each specific medication that the patient has taken could be an enumerated event type. However, the device.implant event type does not have an enumeration.

When querying, event types can be selected at any of the three levels of classification. For example:

  • Specifying patient as the event type would return all events logged by the patient.
  • Querying for patient.medication would return all logged medication events.
  • Specifying patient.medication.propranolol would list all events when the patient recorded taking Propranolol.

Span Timestamps

A span represents something that occurred over time. This is represented in the record via the start_time and end_time keys. A span may also represent some amount of uncertainty in the start and/or end time, via the start_time_min and end_time_max keys. This is most relevant for patient-reported events. For example, if a patient logs that they had a headache for 1-2 hours, starting at 3pm, it would be represented with the following timestamps:

  • start_time_min: 3pm
  • start_time: 3pm
  • end_time: 4pm
  • end_time_max: 5pm

The four possible timestamps always have the following relationship:

start_time_min <= start_time < end_time <= end_time_max

Payloads

Both events and spans include a JSON payload. The contents of the payload varies between different event types.

Event (JSON)

Returns events in a JSON-formatted response.

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
string

ID of the device from which data was reported.

event
string

The type of event to query, in the form namespace.category.enum or some prefix of that (see the "Classification" description above). By default, all event types are returned.

start_time
float

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

end_time
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.

timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

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.

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.

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "success": true
}

Span (JSON)

Returns spans in a JSON-formatted response.

All spans that overlap with the queried time range are included in the response. In other words, if a span starts before but ends after the beginning of the queried time range, it will be included in the response.

This endpoint only supports token-based pagination. It does not support the offset-based pagination query parameters.

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.

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.

device_id
string

ID of the device from which data was reported.

event
string

The type of span to query, in the form namespace.category.enum or some prefix of that (see description above). By default, all types are returned.

timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

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.

Responses

Response samples

Content type
application/json
{
  • "result": {
    },
  • "success": true
}

Heart Rate

Query heart rate data.

Heart Rate (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: "bpm"
Enum: "bpm" "availability(bpm)"

Determines what kind of data is returned:

  • bpm - return heart rate measured as beats per minute (BPM). Defaults to the minimum resolution of 0.01 seconds, unless resolution or frequency are specified.
  • availability(bpm) - return the availability of BPM data: 1 if available, 0 otherwise. Defaults to the minimum resolution of 1 min, unless resolution or frequency are specified.

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

  • first(bpm) - first bpm value from each downsampled time interval.
  • last(bpm) - last bpm value from each downsampled time interval.
  • mean(bpm) - mean bpm value over each downsampled time interval.
  • median(bpm) - median bpm 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
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.

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

Response samples

Content type
application/json
Example
{
  • "result": {
    }
}

Heart Rate (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: "bpm"
Enum: "bpm" "availability(bpm)"

Determines what kind of data is returned:

  • bpm - return heart rate measured as beats per minute (BPM). Defaults to the minimum resolution of 0.01 seconds, unless resolution or frequency are specified.
  • availability(bpm) - return the availability of BPM data: 1 if available, 0 otherwise. Defaults to the minimum resolution of 1 min, unless resolution or frequency are specified.

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

  • first(bpm) - first bpm value from each downsampled time interval.
  • last(bpm) - last bpm value from each downsampled time interval.
  • mean(bpm) - mean bpm value over each downsampled time interval.
  • median(bpm) - median bpm 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
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.

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: 2000000

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

Responses

Response samples

Content type
text/csv
Example
time,bpm
1565304080,64
1565304085,65
1565304090,62

Local Field Potentials

Query local field potential (LFP) data.

LFP (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.

NOTE: Cannot be used in combination with the legacy channels parameter.

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.

NOTE: Cannot be used in combination with the legacy channels parameter.

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

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

Note that this parameter has the same meaning as channels, but causes a different return data schema to be used. channels has been deprecated and is available only for backwards compatibility.

NOTE: Cannot be used in combination with the legacy channels parameter.

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

(Deprecated. Use channel instead)

Comma-separated list of device-sensing channels, identified by channel number (e.g. 0, 1, 2, or 3).

NOTE: Cannot be used in combination with the algorithm, anatomy, channel, or sensor parameter.

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.

NOTE: Cannot be used in combination with the legacy channels parameter.

expression
string
Default: "lfp"

Determines what kind of data is returned. Some expressions involve statistical aggregations or downsampling (e.g. first(lfp), mean(lfp), etc). These require frequency or resolution to be specified.

  • lfp - local field potential (default). Defaults to the minimum resolution of 0.001 seconds, unless resolution or frequency are specified.
  • availability(lfp) - availability of LFP data: 1 if available, 0 otherwise. Defaults to the minimum resolution of 1 min, unless resolution or frequency are specified. If deprecated parameter channels is specified the default minimum resolution is 5 min.
  • first(lfp) - first LFP value from each downsampled time interval.
  • last(lfp) - last LFP value from each downsampled time interval.
  • mean(lfp) - mean LFP value over each downsampled time interval.
  • median(lfp) - median LFP value over each downsampled time interval.
  • spectrogram(lfp) - spectrogram data from a FFT, at 1Hz resolution. This is calculated using scipy.signal.spectrogram() with default settings and nperseg set to the sampling frequency. In the result, each channel's data contains one element per frequency. This element is itself an array, with one float per timestamp. y contains the corresponding frequencies, and time contains the timestamps.
  • projection(spectrogram(lfp),y,z) - projection of the spectrogram's power over frequency. In the result, x contains frequency, and y contains power (per channel).
  • projection(mean(spectrogram(lfp)),y,z) - the spectrogram is downsampled by taking the mean power over some time interval (set by frequency or resolution), for each frequency. The projection of this result (power over frequency) is returned.
  • mean_std(projection(spectrogram(lfp),y,z)) - for each frequency, return the mean and standard deviation of the spectrogram power. In the result, point_count contains the number of data points that contributed to the summary statistics.
  • percentiles(projection(spectrogram(lfp),y,z)) - for each frequency, return percentiles (10, 25, 50, 75, and 90) of the spectrogram power. In the result, point_count contains the number of data points that contributed to the summary statistics.
  • band_power(spectrogram(lfp)) - returns the average power of the LFP spectrogram, over some frequency range. Requires low_freq and high_freq parameters to be set.
  • frequency_spectrum - returns an FFT of local field potential data. Unlike the spectrogram expressions, which return data computed by Rune, this is from the device itself. The details of the FFT computation are thus dependent on the device type.
low_freq
integer [ 0 .. 200 ]
Default: 0

For expressions that return frequency data (e.g. spectrograms), this is the lowest frequency to select (in Hz). Note that this is not related to the frequency parameter.

high_freq
integer [ 0 .. 200 ]
Default: 125

For expressions that return frequency data (e.g. spectrograms), this is the highest frequency to select (in Hz). Note that this is not related to the frequency parameter.

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
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.

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

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "result": {
    }
}

LFP (CSV)

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

  • channels will trigger use of the legacy response schema. Omit or use channel instead for the (latest) version 1.0 schema.
  • 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.

NOTE: Cannot be used in combination with the legacy channels parameter.

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.

NOTE: Cannot be used in combination with the legacy channels parameter.

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

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

Note that this parameter has the same meaning as channels, but causes a different return data schema to be used. channels has been deprecated and is available only for backwards compatibility.

NOTE: Cannot be used in combination with the legacy channels parameter.

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

(Deprecated. Use channel instead)

Comma-separated list of device-sensing channels, identified by channel number (e.g. 0, 1, 2, or 3).

NOTE: Cannot be used in combination with the algorithm, anatomy, channel, or sensor parameter.

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.

NOTE: Cannot be used in combination with the legacy channels parameter.

expression
string
Default: "lfp"
Enum: "lfp" "availability(lfp)" "spectrogram(lfp)"

Determines what kind of data is returned:

  • lfp - local field potential. (default)
  • availability(lfp) - availability of LFP data: 1 if available, 0 otherwise.
  • first(lfp) - first LFP value from each downsampled time interval.
  • last(lfp) - last LFP value from each downsampled time interval.
  • mean(lfp) - mean LFP value over each downsampled time interval.
  • median(lfp) - median LFP value over each downsampled time interval.
  • spectrogram(lfp) - spectrogram data from a FFT, at 1Hz resolution. Each frequency is returned as a separate column in the result.
  • frequency_spectrum - returns an FFT of local field potential data. Unlike the spectrogram expression, which returns data computed by Rune, this is from the device itself. The details of the FFT computation are thus dependent on the device type.
low_freq
integer [ 0 .. 200 ]
Default: 0

For expressions that return frequency data (e.g. spectrograms), this is the lowest frequency to select (in Hz). Note that this is not related to the frequency parameter.

high_freq
integer [ 0 .. 200 ]
Default: 125

For expressions that return frequency data (e.g. spectrograms), this is the highest frequency to select (in Hz). Note that this is not related to the frequency parameter.

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.

timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

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.

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: 2000000

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

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

Response samples

Content type
text/csv
Example
timestamp,algorithm,anatomy,channel,sensor,potential
1590706215.314000,example-dbs-v2,GPi,0,7-5,0.1
1590706231.971000,example-dbs-v2,GPi,0,7-5,1.2
1590706240.604000,example-dbs-v2,STN,0,7-5,2.3
1590706248.245000,example-dbs-v2,STN,2,0-2,3.4
1590706257.554000,example-dbs-v2,STN,2,0-2,-4.5

Rotation

Query rotation data for any device that records it. Rotation is represented as three vectors: x, y, z. Each vector contains the angular velocity along its respective axis.

Rotation (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:

  • channels will trigger use of the legacy response schema. Omit or use channel instead for the (latest) version 1.0 schema.
  • 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: "rotation"
Enum: "rotation" "availability(rotation)"

Determines what kind of data is returned.

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

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

  • first(rotation) - first rotation value from each downsampled time interval.
  • last(rotation) - last rotation value from each downsampled time interval.
  • mean(rotation) - mean rotation value over each downsampled time interval.
  • median(rotation) - median rotation 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
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.

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

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "result": {
    }
}

Rotation (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: "rotation"
Enum: "rotation" "availability(rotation)"

Determines what kind of data is returned.

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

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

  • first(rotation) - first rotation value from each downsampled time interval.
  • last(rotation) - last rotation value from each downsampled time interval.
  • mean(rotation) - mean rotation value over each downsampled time interval.
  • median(rotation) - median rotation 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
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.

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: 2000000

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

Responses

Response samples

Content type
text/csv
Example
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

Sessions

Fetch raw device data from a single stream of a device data session.

Note that unlike other endpoints, this endpoint returns the raw binary of the original data, as was uploaded by the client to the Rune Ingestion API. It does not have a standard JSON or CSV structure.

A data session may be composed of several streams (files), so you will need to make one request per stream to download all of the files for the given recording. Requests can be made in parallel to optimize performance.

The typical use for this endpoint is download a data session into a local file. This is not the optimal way to download entire archives. If for any reason you need to export all data for all your patients, please contact support@runelabs.io, and our team will provide you with a copy of the raw data in a more efficient way.

You will need to know the Session ID to use this endpoint. This is the unique Dataset ID received from the Rune Data Upload API, not the device session ID provided by the upload client. Rune’s Graph API can be used to list data sessions for a given patient.

Sessions

query Parameters
session_id
required
string

ID of the data session, as specified by the device during upload.

stream_name
required
string

The name of the specific stream to download from the dataset. Streams vary by device.

Responses

Response samples

Content type
application/json
{
  • "success": false,
  • "error": {
    },
  • "result": null
}

State

Stateful streams are a category of data distinguished by the fact that they persistently hold a constant value over time, until an update event sets a new value at a given point in time. After an update event sets the value of a field, that value persists until the next update event, and so on.

Because many different streams can be categorized as stateful, data from these endpoints are grouped into event types. Much like events, these represent different types of data. Each event type contains different state fields, which store numeric values. Each update event may affect one or more of the state fields.

As an example, suppose a device periodically emits status events. Each event contains two fields:

  • is_on reflects a change in the on/off status for the device
  • battery_level represents the charge status of the battery, as a percentage (0-1).

Suppose the device is turned on at time T0 with a battery level of 90%, and it issues its first status update. At time T1, the device emits a status update that the battery level is at 70%. At time T2, the device is turned off, with a battery level of 65%. If you queried the state of the status stream for this device, you would see the following:

  • Before T0, the stream has no data.
  • At every time between T0 and T1, is_on=1 and battery_level=0.9
  • Between T1 and T2, is_on=1 and battery_level=0.7
  • After time T2, is_on=0 and battery_level=0.65

State (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, event, and fields determine the structure of the result object.
  • timestamp determines the format of the timestamps.
  • partition_size segments each stream 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: "state"
Enum: "state" "availability(state)" "event_type" "update"

Determines what kind of data is returned:

  • state - return the state of the device. See event and fields parameters.
  • availability(state) - return the availability of each field of the state data: 1 if available, 0 otherwise.
  • event_type - return all event types that were emitted from a single device (over all time).
  • update - return the updates that were made to an event type, over the given time range. It is NOT necessary to specify the fields parameter. By default, the result includes all fields that were updated at a particular timestamp.
event
required
string
Example: event=stimulation_state

Type of state event to return data for. This parameter is NOT required for the event_type expression, which may be used to discover which event types were emitted by a specified device.

fields
required
string
Example: fields=ld0.threshold.low,ld0.threshold.high

Comma-separated list of state fields to return as timeseries data. This parameter is NOT required for the event_type or update expressions. The update expression may be used to discover which fields were updated within a specified time range.

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.

Only supported for the availability expression.

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.

Only supported for the availability expression.

timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

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.

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

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "result": {
    }
}

State (CSV)

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

  • expression, event, and fields determine the structure of the result object.
  • 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: "state"
Enum: "state" "availability(state)"

Determines what kind of data is returned:

  • state - return the state of the device. See event and fields.
  • availability(state) - return the availability of each field of the state data: 1 if available, 0 otherwise.
event
required
string
Example: event=stimulation_state

Type of state event to return data for.

fields
required
string
Example: fields=ld0.threshold.low,ld0.threshold.high

Comma-separated list of state fields to return as timeseries data.

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.

Only supported for the availability expression.

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.

Only supported for the availability expression.

timestamp
string
Default: "unix"
Enum: "unix" "datetime" "iso"

Timestamp format.

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.

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: 2000000

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

Responses

Response samples

Content type
text/csv
Example
time,ld0.threshold.low,ld0.threshold.high
1565304080.1,500,503
1565304500.2,500,505
1565304910.3,501,505

Symptom Probability

Query the percentage of time during which a symptom was detected.

Symptom Probability (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 and severity determine the structure of the result object.
  • timestamp determines the format of the timestamps.
  • partition_size segments each stream 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.

symptom
required
string

Name of the symptom (e.g. tremor)

expression
string
Default: "probability"

Determines what kind of data is returned:

  • probability - return the percentage of time that the symptom was detected during each window of time. Defaults to resolution of 1 min, unless resolution or frequency are specified. Depending on the value of the severity parameter, this may be a single stream (with the probability of the symptom occurring at all) or multiple streams (the probability of symptom severities). See details for the severity parameter.

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

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

  • first(probability) - first probability value from each downsampled time interval.
  • last(probability) - last probability value from each downsampled time interval.
  • mean(probability) - mean probability value over each downsampled time interval.
  • median(probability) - median probability value over each downsampled time interval.
severity
string
Example: severity=mild,moderate,severe

A comma-delimited list of symptom severities OR * (to select all available).

This parameter is only used when expression=probability, and only with symptoms for which severity data is available (e.g. tremor). It affects the format of the response data (see response examples):

  • If no severity is specified, the API will return a single stream of values, representing the percentage of the time window during which the symptom was detected (to any extent) at each returned point in time.
  • If 1+ severities are specified (in a comma-delimited list), the API will return 1 stream independently for each severity.
  • If severity=*, the response contains 1 stream for each severity that exists in the window of time queried.

Timeseries Alignment: When severity is specified, results are bucketed by time, in order to align multiple timeseries. Data is averaged within each bucket. The size of the time buckets may be set via the frequency or resolution parameter. By default, 60s buckets are used.

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
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.

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

Response samples

Content type
application/json
Example
{
  • "success": true,
  • "result": {
    }
}

Symptom Probability (CSV)

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

  • expression and severity determine 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.

symptom
required
string

Name of the symptom (e.g. tremor)

expression
string
Default: "probability"

Determines what kind of data is returned:

  • probability - return the percentage of time that the symptom was detected during each window of time. Defaults to resolution of 1 min, unless resolution or frequency are specified. Depending on the value of the severity parameter, this may be a single stream (with the probability of the symptom occurring at all) or multiple streams (the probability of symptom severities). See details for the severity parameter.

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

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

  • first(probability) - first probability value from each downsampled time interval.
  • last(probability) - last probability value from each downsampled time interval.
  • mean(probability) - mean probability value over each downsampled time interval.
  • median(probability) - median probability value over each downsampled time interval.
severity
string
Example: severity=mild,moderate,severe

A comma-delimited list of symptom severities OR * (to select all available).

This parameter is only used when expression=probability, and only with symptoms for which severity data is available (e.g. tremor). It affects the format of the response data (see response examples):

  • If no severity is specified, the API will return a single stream of values, representing the percentage of the time window during which the symptom was detected (to any extent) at each returned point in time.
  • If 1+ severities are specified (in a comma-delimited list), the API will return 1 stream independently for each severity.
  • If severity=*, the response contains 1 stream for each severity that exists in the window of time queried.

Timeseries Alignment: When severity is specified, results are bucketed by time, in order to align multiple timeseries. Data is averaged within each bucket. The size of the time buckets may be set via the frequency or resolution parameter. By default, 60s buckets are used.

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
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.

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: 2000000

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

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

Response samples

Content type
text/csv
Example
time,probability
1565304080.1,0.5
1565304080.2,0.7
1565304080.3,0.6