Requesting historical health data (REST API requests)
Learn how to request for historical data to be sent to your destination through the REST API
Last updated
Was this helpful?
Learn how to request for historical data to be sent to your destination through the REST API
Last updated
Was this helpful?
Terra API is event-based, meaning you don’t need to manually request data via the API.
For new and ongoing data updates, Terra API automatically sends them to your configured Data Destination (e.g. Webhook, Database, or cloud storage bucket).
If you need historical user data, you can request it using the Health & Fitness API endpoints by specifying the user ID, data type, and time range. This allows you to request past records on demand.
In this guide you will learn:
When are historical data requests useful?
How to use the Terra Dashboard to make a historical data request?
How to use the Terra's Health & Fitness API to make a historical data request?
Request Parameters (e.g. send to destination and include samples)
How to handle requests of very long time ranges ?
In order to receive Data as Events, you'll need to:
Obtain your Terra API Key and dev-id from your Terra Dashboard
Set up a Data Destination where Terra will send event and data updates.
Enable the specific data sources your app requires (e.g., activity, sleep).
Connected at least a user. Requests are done using a user_id
and at least a date.
The must be connected via Terra's Health & Fitness API.
The user_id
is needed to make requests for historical data
When an end user first connects an account (e.g. wearable, device, health app), you will by default only receive data from that point onwards.
If you would like to build a historical health & fitness profile of the user, to establish baselines for statistics, or for any other calculations, you can make a request to Terra for data from prior to the user's authentication.
Garmin: 5 years into the past, from the current point in time. This is subject to Garmin's backfill limits.
Polar: 30 days into the past, but not prior to the moment the user granted permission.
Health Connect: 30 days into the past, but not prior to the moment the user granted permission.
As a fallback, you should implement a "pull down to refresh" functionality or alternative (like a sync now button, etc...).
Hitting this button should trigger a data pull of the last e.g. 14 days of data for the user, for all the data types you ingest.
You may want your customer support team to use the Terra dashboard to debug by re-sending data, or verifying whether or not Terra fetches the data correctly. See the guide below for a step by step tutorial on how to do so.
To request historical data, the following request parameters are required:
user_id
(required)
start_date
(required)
Terra's Data Retrieval endpoints include many other useful and important parameters.
with_samples
must be set to true
to receive granular data (refer toIntegration setup)
to_webhook
must be set to true
if you want to receive data asynchronously to your Destination. For synchronous data retrieval (if your use case is time-sensitive), just set this parameter to false
.
When making a to_webhook=true
request, keep track of the value of the terra-reference
header.
When the event is eventually sent to your Data Destination, the event's terra-signature
will match that of the initial request, allowing you to mark off the data transfer as successfully completed.
Taking Python FastAPI as an example framework, you may set up your server code to look like the following:
When making a to_webhook=true
request, keep track of the value of the terra-reference
header. When the event is eventually sent to your webhook, the event's terra-reference
will match that of the initial request, allowing you to mark off the data transfer as successfully completed
Following a large request, you will receive the following:
When a large request is made, Terra will send the data to you in chunks of:
at most 10MB
at most 10 objects in the data
array
The chunk size will be limited by whichever of the two limits gets hit first.
ALL chunks will contain the same terra-reference
header value.
Once the number of payloads indicated with the same terra-reference
header value have been received, you can consider the data transfer request complete.
Some impose limits on how far back a developer can request data. Those are:
To request historical data from your Backend, you need to call one of the . Refer to the section for further details on usage.
Refer to the section for further details on usage.
You will immediately receive a event.
This indicates that Terra has acknowledged the large request and is currently processing the data retrieval from the .
Once data retrieval has finished, Terra will organise the data into chunks, and send a payload, indicating the number of payloads to expect.