​
Backfill (Historical Data)

After successfully creating a Spike API integration, a data stream of wearables recorded data becomes available for the application user when making API calls and also through webhooks. Usually only data recorded from the moment of authorization is shared, but Spike has developed mechanisms to fetch data recorded retrospectively as well. This document describes the feature called Backfill and principles of how to use it, as well as the limitations.

​
Configuration

In the admin console, under Application configuration you can find the setting called “Max Backfill (days)”. By default it’s disabled (set to nothing or 0). To enable the backfill mechanism you need to set the value to the required number of days and save it.

​
Core Principles

Once backfill is enabled and new integration gets created, here’s what you should expect:
  • Timing: Backfill is triggered post new integration creation. Settings would have no effect on integrations that are already created and have the same data accumulated by natural lifecycle
  • Data Delivery: Data delivery (API and webhooks) is unified, but backfilling process is unique to each provider
  • Asynchronous Processing: Backfilling mostly is an asynchronous process. Seeking the best user experience for application users, they will see integration being successfully created (redirected back to configured postback URL) and the process might continue in the background

​
Implementation Categories

​
Manual Implementation Required

Some providers require manual data extraction through SDK calls:

​
Apple HealthKit

Data is stored exclusively on the device (iPhone). Manual implementation is required because Apple doesn’t offer any other communication except the HealthKit framework. Limitations:
  • What data the user has on their device
  • What permissions your app has been granted (read access for specific data types)
  • User’s health app settings or deletions
  • Your retention policy settings
Implementation: See iOS SDK Backfill Guide for detailed implementation instructions.

​
Google Health Connect

Data is stored exclusively on the device (running Android). Manual implementation is required because Google doesn’t offer any other communication except the Health Connect client. Limitations:
  • What data the user has on their device
  • What permissions your app has been granted (read access for specific data types)
  • User’s health app settings or deletions
  • Your retention policy settings
  • 30 days period predating permission grant
Special Considerations:
  • Permission request timing is not relevant - if an application user decides to approve permission a week later by going directly into Health Connect settings menu, you will be able to access data 23 days prior to installing the app
  • For apps targeting Android API level 34 (Android 14) and higher, Google has introduced PERMISSION_READ_HEALTH_DATA_HISTORY which allows access to health data recorded before the app was installed
Implementation: See Android SDK Backfill Guide for detailed implementation instructions.

​
Automatic Backfill

Most third-party providers handle backfill automatically with no additional effort required from your side. Each provider has different availability windows and processing times. For complete details on each provider’s backfill capabilities, availability windows, and specific limitations, refer to the Supported Providers documentation.

​
Best Practices

​
For Manual Implementation (iOS/Android)

  • Keep the backfill process asynchronous for optimal user experience
  • Segment requests into smaller date ranges to ensure optimal performance
  • Implement rate limiting to avoid overwhelming the health data store
  • Handle permissions gracefully - users may grant partial access
  • Provide meaningful feedback about data access issues

​
For Automatic Backfill

  • Listen for incoming webhooks to know when data becomes available
  • Be patient with the asynchronous process - some providers may take hours
  • Understand that data may not arrive in chronological order
  • Consider the varying limitations across providers when setting expectations

​
General Recommendations

  • Set realistic backfill periods considering provider limitations
  • Implement robust error handling for various scenarios
  • Respect user privacy and data access permissions
  • Design your application to handle partial or delayed data availability

​
Provider-Specific Details

For complete details on each provider’s capabilities, limitations, and backfill availability, refer to the Supported Providers documentation. For platform-specific implementation guides:

​
Monitoring and Troubleshooting

To effectively monitor backfill operations:
  1. Webhook Monitoring: Set up webhook listeners to track when historical data becomes available
  2. Error Handling: Implement comprehensive error handling for permission issues, data unavailability, and provider limitations
  3. User Communication: Provide clear feedback to users about the backfill process and expected timelines
  4. Logging: Maintain detailed logs of backfill requests and outcomes for debugging purposes