Timeseries

The Timeseries endpoint allows you to retrieve time-series data for various biometric signals.

GET /v1/timeline/timeseries/{user_id}/{type}

Parameters

Name	Type	In	Description
user_id	UUID	Path	The unique identifier for the user.
type	Enum	Path	The type of measurement to retrieve. See Measurement Types for allowed values.
start_date	Date	Query	The start date for the query period (format: YYYY-MM-DD).
end_date	Date	Query	The end date for the query period (format: YYYY-MM-DD).
days	Integer	Query	Days per page (default 1, max 7). Only applies to application/json cursor-based pagination.
cursor	String	Query	Pagination cursor from the previous response. Only supported on application/json; returns 400 for CSV and Parquet.

Response Formats

You can specify the desired response format using the Accept header.

Header Value	Format
application/json	JSON (default)
text/csv	CSV
application/octet-stream	Apache Parquet

Response Status Codes

200 ok

The request was successful. A date range with no data returns 200 with empty arrays in data.

400 bad request

An invalid cursor was supplied, or cursor was combined with text/csv or application/octet-stream.

406 not acceptable

An unsupported Accept header was requested.

See Errors for authentication, validation, and rate-limit responses.

---

Measurement Types

HEART_RATE

Continuous Heart Rate, measured in beats per minute (bpm).

• Granularity: 10 seconds
• Quality Indicator: 1 to 4 (4 = best).

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/HEART_RATE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:00:10.000Z"],
        "value": [65, 66],
        "quality_indicator": [4, 4]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/HEART_RATE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value,quality_indicator
2024-04-01T12:00:00.000Z,65,4
2024-04-01T12:00:10.000Z,66,4

ACTIVITY_COUNT

A measure of movement. Higher values indicate greater movement.

• Granularity: 1 second

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_COUNT?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-07-01T00:00:04.000Z", "2024-07-01T00:00:05.000Z"],
        "value": [52, 54]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_COUNT?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value
2024-07-01T00:00:04.000Z,52
2024-07-01T00:00:05.000Z,54

ACTIVITY_TYPE

Categorical activity type.

Since the granularity is 1 second, the ACTIVITY_TYPE endpoint only returns values when there is either a change in the type or a change in the quality occurs. To retrieve the 1 second granularity you must forward fill the data.

• Granularity: 1 second
• Values: UNSPECIFIED, OTHER, WALK, RUN, CYCLE, REST

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_TYPE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:00:01.000Z"],
        "value": ["REST", "WALK"],
        "quality_indicator": [4, 3]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/ACTIVITY_TYPE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value,quality_indicator
2024-04-01T12:00:00.000Z,REST,4
2024-04-01T12:00:01.000Z,WALK,3

STEPS

Number of steps detected. Steps are sent from the watch in batches when at least 12 new steps are recorded since the previous batch.

• Granularity: Event-based

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/STEPS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:05:10.000Z", "2024-04-01T12:05:45.000Z"],
        "value": [15, 25]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/STEPS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value
2024-04-01T12:05:10.000Z,15
2024-04-01T12:05:45.000Z,25

MOTION

A motion intensity value, ranges between 0.0-100.0. Each sample also carries a label that bins the value into an intensity band, derived from the underlying sensor reading.

• Granularity: 1 minute
• Values (label): REST, LIGHT, MILD, MODERATE, VIGOROUS

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/MOTION?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:01:00.000Z"],
        "value": [1.22, 30.52],
        "label": ["REST", "MODERATE"]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/MOTION?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value,label
2024-04-01T12:00:00.000Z,1.22,REST
2024-04-01T12:01:00.000Z,30.52,MODERATE

SKIN_TEMPERATURE

Skin temperature, measured in Celsius.

• Granularity: 5 seconds

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_TEMPERATURE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:00:05.000Z"],
        "value": [34.5, 34.6]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_TEMPERATURE?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value
2024-04-01T12:00:00.000Z,34.5
2024-04-01T12:00:05.000Z,34.6

REACTIVITY_MONITOR

The user's reactivity state for each minute (categorical; no numeric value).

• Granularity: 1 minute
• Values: LOW_REACTIVITY, HOMEOSTASIS, STRESS_RESPONSE, PHYSICAL_ACTIVITY

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/REACTIVITY_MONITOR?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:01:00.000Z"],
        "state": ["HOMEOSTASIS", "STRESS_RESPONSE"]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/REACTIVITY_MONITOR?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,state
2024-04-01T12:00:00.000Z,HOMEOSTASIS
2024-04-01T12:01:00.000Z,STRESS_RESPONSE

SKIN_CONDUCTANCE_LEVEL

Continuous skin conductance, measured in microSiemens (µS).

• Granularity: 5 seconds

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_CONDUCTANCE_LEVEL?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:00:05.000Z"],
        "value": [0.1, 0.12]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/SKIN_CONDUCTANCE_LEVEL?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value
2024-04-01T12:00:00.000Z,0.1
2024-04-01T12:00:05.000Z,0.12

INTERBEAT_INTERVALS

Interbeat intervals (IBI) — the time between consecutive heartbeats — derived from detected heartbeats, measured in milliseconds (ms).

• Granularity: Event-based and irregular; depends on reliable beat detection, so more data is available during rest / low motion.
• Values outside 100–2000 ms are filtered out as physiologically implausible.

cURL (JSON)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/INTERBEAT_INTERVALS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: application/json"

JSON Response

{
    "data": {
        "datetime": ["2024-04-01T12:00:00.000Z", "2024-04-01T12:00:01.000Z"],
        "value": [812, 799],
        "quality_indicator": [4, 4]
    },
    "next_cursor": null
}

cURL (CSV)

curl -X GET "https://research-api.nowatch.com/v1/timeline/timeseries/{user_id}/INTERBEAT_INTERVALS?start_date=...&end_date=..." \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Accept: text/csv"

CSV Response

datetime,value,quality_indicator
2024-04-01T12:00:00.000Z,812,4
2024-04-01T12:00:01.000Z,799,4

For more information

See the Biometrics documentation for more details on these metrics.