Skip to main content

What Data Is Available Through the Fulcra Life API?

F
Written by Fulcra Team
Updated over a week ago

Last Updated: August 21, 2025

The Fulcra Life API provides comprehensive access to behavioral, biometric, and lifestyle data collected through Fulcra's platform. This article provides a detailed overview of the extensive data types and capabilities available through the API.

Overview of Available Data Categories

The Fulcra Life API organizes data into several key categories, each providing rich, granular access to different aspects of personal health and lifestyle information.

1. Time Series Metrics

The API provides access to over 200 distinct, precisely-defined metrics across comprehensive health domains. Each metric includes detailed descriptions, units, data types (discrete/cumulative), and specific value column mappings.

Core Metric Categories:

Cardiovascular Health Metrics:

  • AFibBurden: Percentage of time showing signs of atrial fibrillation during monitoring periods

  • HeartRate: User's heart rate measurements

  • RestingHeartRate: Baseline heart rate during rest periods

  • HeartRateVariabilitySDNN: Heart rate variability standard deviation measurements

  • WalkingHeartRate: Heart rate during walking activities

  • HeartRateRecoveryOneMinute: Heart rate recovery after one minute post-exercise

  • HighHeartRateEvent: Events indicating elevated heart rate

Activity and Exercise Metrics:

  • StepCount: Count of steps taken by the user

  • ActiveCaloriesBurned: Cumulative active energy expenditure

  • BasalCaloriesBurned: Basal metabolic energy expenditure

  • DistanceTraveledOnFoot: Distance covered while walking or running

  • CyclingPower: Power output during cycling activities

  • RunningSpeed: Speed measurements during running

  • SwimmingStrokeCount: Stroke count during swimming sessions

Sleep Analysis Metrics:

  • SleepStage: Discrete sleep stage classifications (in bed, awake, light sleep, deep sleep, REM)

  • SleepChanges: Transitions between sleep stages

  • SleepApneaEvent: Sleep apnea detection events

  • SleepingWristTemperature: Temperature readings during sleep

  • SleepingBreathingDisturbances: Breathing irregularities during sleep

Nutrition and Dietary Metrics (25+ available):

  • CaloriesConsumed: Total caloric intake

  • DietaryProteinConsumed: Protein intake measurements

  • DietaryVitaminCConsumed: Vitamin C intake tracking

  • Plus 20+ additional vitamins, minerals, and macronutrient metrics

Clinical Symptoms (30+ tracked):

  • SymptomFatigue: Fatigue level reporting with severity scales

  • SymptomHeadache: Headache occurrence and intensity

  • SymptomNausea: Nausea symptoms and severity

  • Plus 25+ additional symptom tracking metrics

Reproductive Health Metrics (12+ available):

  • MenstrualFlow: Menstrual flow tracking

  • OvulationTestResult: Ovulation test outcomes

  • PregnancyTestResult: Pregnancy test results

  • CervicalMucusQuality: Cervical mucus observations

  • Plus additional women's health tracking metrics

Environmental Metrics:

  • Audio exposure levels and ambient sound measurements

  • UV exposure tracking

  • Water temperature readings

  • Time spent in daylight

2. Advanced Data Processing Functions

Beyond basic metric retrieval, the API provides sophisticated data processing capabilities:

Sleep Cycle Analysis

The sleep_cycles() function processes raw sleep stage data into comprehensive cycle summaries:

  • Multiple sleep cycles per night with precise timing

  • Stage-by-stage breakdowns with millisecond precision

  • Calculated metrics including total sleep time, sleep latency, and time in each stage

  • Detailed interval tracking and cycle gap analysis

  • Support for custom cycle gap parameters and stage filtering

Location Intelligence

Comprehensive location tracking beyond basic GPS data:

  • High-frequency location tracking via location_time_series()

  • Point-in-time location queries with location_at_time()

  • Configurable precision controls using change_meters parameter

  • Optional reverse geocoding integration for address resolution

  • Apple and Google Maps location update processing

Workout Data Processing

The apple_workouts() function returns extensive structured workout data, including:

  • Detailed workout sessions with start/end times

  • Exercise type classification and duration tracking

  • Associated health metrics during workout periods

  • Equipment and device information

  • Performance metrics and workout intensity data

3. Raw Sample Data Access

For detailed analysis, the API provides access to raw underlying samples through metric_samples():

  • Individual data points with exact timestamps

  • Source device and application information

  • Data quality indicators and accuracy measurements

  • Overlapping sample resolution for multi-source data

  • Complete metadata including device properties and software versions

4. Calendar and Event Integration

Calendar Events:

  • Complete calendar event retrieval with calendar_events()

  • Event details including location, participants, and notes

  • Multi-calendar support with filtering capabilities

  • Time zone handling and recurrence rule processing

  • Integration with Apple Calendar and other calendar sources

Calendar Management:

  • Calendar inventory and metadata via calendars()

  • Calendar source identification and color coding

  • Permission and sharing status information

5. Annotation System

The API supports multiple types of user annotations for contextualizing data:

Boolean Annotations: Simple true/false markers for events or states Duration Annotations: Time-based annotations with start and end periods Moment Annotations: Point-in-time contextual markers Numeric Annotations: Quantitative user-reported values Scale Annotations: Subjective ratings and scaled responses

6. Time Series Data Retrieval

Single Metric Time Series: Use metric_time_series() for individual metric analysis with:

  • Configurable sample rates (sub-second to hourly)

  • Custom time range specification

  • Null value handling options

  • Additional calculation parameters

Multi-Metric Time Series: Use time_series_grouped() for comprehensive analysis:

  • Query multiple metrics simultaneously

  • Synchronized time indexing across all metrics

  • Pandas DataFrame output for analysis workflows

  • Efficient data aggregation and processing

7. Authentication and User Management

User Information Access:

  • User profile and preference retrieval via get_user_info()

  • Time zone and calendar preference management

  • Account creation and modification history

  • Data sharing and permission settings

Shared Dataset Access:

  • Access to datasets shared by other users via get_shared_datasets()

  • Permission-based data access control

  • Collaborative research and family sharing support

8. Device and Source Tracking

All data points include comprehensive source attribution:

  • Device identification (wearables, smartphones, manual entry)

  • Application source tracking

  • Data quality and accuracy indicators

  • Version information for devices and software

  • Source prioritization for overlapping data

API Technical Specifications

Authentication

  • OAuth 2.0 Device Authorization Flow via Auth0

  • Bearer token authentication for all requests

  • Refresh token support for long-running applications

  • Time zone-aware request processing

Data Formats

  • JSON response format for all endpoints

  • Pandas DataFrame integration via Python client library

  • ISO 8601 timestamp formatting with timezone support

  • Standardized unit specifications for all metrics

Rate Limiting and Performance

  • Authenticated access required for all data endpoints

  • Optimized for both real-time and batch data retrieval

  • Support for large-scale data exports and analysis workflows

Getting Started

To begin using the Fulcra Life API:

  1. Explore Available Metrics: Use the metrics_catalog() function to get a complete list of available metrics with descriptions and specifications

  2. Authentication Setup: Configure OAuth authentication using the Python client library or direct API calls

  3. Data Retrieval: Start with basic time series queries using metric_time_series() or time_series_grouped()

  4. Advanced Analysis: Leverage specialized functions like sleep_cycles() and location_time_series() for sophisticated data processing

The Fulcra Life API represents a comprehensive health data platform with capabilities far exceeding basic metric tracking, providing researchers, developers, and users with unprecedented access to detailed personal health and lifestyle data.

Related Articles
Is there a minimum amount of data that makes this application useful?
Data Glossary
I don't use iOS or Apple Calendars, or I'd like to add an additional calendar account to Context and my Fulcra Data Store
What are Annotations?
My Step Count, Calorie Count, or Walking and Running Distance Seem Wrong
Did this answer your question?