Skip to main content

Quickstart

This guide walks you through making your first successful call to POST /predict, the main endpoint of the Sensia API. By the end of this page you'll understand how to structure your request, interpret the response, and use historical session data to improve accuracy over time.

Prerequisites​

  • A Sensia API key (get one here)
  • curl, Python, or any HTTP client

Step 1: Prepare your session data​

A session requires sleep data from the previous night and biometric readings from the hour before the prediction.

At minimum, the model needs:

  • Heart rate time series for the day (HR_day_1h) and night (HR_night_imputed)
  • Respiratory rate for the day (RR_day_1h) and night (RR_night_imputed)
  • Sleep stage breakdown in seconds (deep, REM, light percentages and the total sleep time including the awake time)
  • Basic demographics of the individual (age, height, weight, sex)

Please note that the the model is able to provide an answer even if some of the fields are missing, but providing as much data as possible will improve the accuracy of the predictions. For a more in-depth description please see the Session Data documentation →.
Historical value can, and should be provided to further improve the accuracy of the model. If you have access to past sessions, include them in the past_sessions array along with their corresponding scores in the past_targets array as described in Step 4.

Step 2: Make a non-baseline request​

In order to get a prediction, send a POST request to https://api.sensia.bio/predict with the session data in the body. Please make sure to include your API key in the X-API-Key header and set Content-Type to application/json.
Below is an example request using curl and Python's requests library. Replace the session data with your own values and use your actual API key.

curl -X POST https://api.sensia.ai/predict \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "current_session": {
      "HR_day_1h": [72.5, 74.1, 73.0, 71.8],
      "HR_night_imputed": [60.2, 61.0, 59.8, 60.5],
      "RR_day_1h": [16.0, 15.8, 16.2, 15.9],
      "RR_night_imputed": [14.5, 14.0, 14.2, 13.9],
      "sleepTimeSeconds": 28800,
      "deepPercentage": 0.20,
      "remPercentage": 0.25,
      "lightPercentage": 0.55,
      "deepSleepSeconds": 5760,
      "remSleepSeconds": 7200,
      "lightSleepSeconds": 15840,
      "awakeSleepSeconds": 600,
      "age": 35,
      "height_cm": 175,
      "weight_kg": 72.5,
      "sex": "M"
    }
  }'
Python
import requests

response = requests.post(
    "https://api.sensia.ai/predict",
    headers={
        "X-API-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "current_session": {
            "HR_day_1h": [72.5, 74.1, 73.0, 71.8],
            "HR_night_imputed": [60.2, 61.0, 59.8, 60.5],
            "RR_day_1h": [16.0, 15.8, 16.2, 15.9],
            "RR_night_imputed": [14.5, 14.0, 14.2, 13.9],
            "sleepTimeSeconds": 28800,
            "deepPercentage": 0.20,
            "remPercentage": 0.25,
            "lightPercentage": 0.55,
            "deepSleepSeconds": 5760,
            "remSleepSeconds": 7200,
            "lightSleepSeconds": 15840,
            "awakeSleepSeconds": 600,
            "age": 35,
            "height_cm": 175,
            "weight_kg": 72.5,
            "sex": "M",
        }
    },
)
print(response.json())

Learn more about the Session Data fields → and how to Structure the input Json → to understand how to format your request body correctly.

Step 3: Read the response​

A successful response looks like this:

{
    "inference_time_ms": 1.216,
    "stress": 24.7,
    "memory": 44.5,
    "reasoning": 56.3,
    "attention": 58.3,
    "C_SCORE": 55.8,
    "valence": "High",
    "arousal": "Low"
}

All mental scores are on a 0–100 scale, emotional index are classified as "Low" or "High", while inference_time_ms indicates how long the model took to generate the prediction. For more information on what each score means, see the Output Scores documentation →.

Step 4: Add historical context (optional)​

To improve accuracy, include up to 5 past sessions and their previously returned scores:

{
  "current_session": { "..." },
  "past_sessions": [
    { "...previous session data..." }
  ],
  "past_targets": [
    {
      "C_SCORE": 62.1,
      "attention": 65.0,
      "memory": 58.2,
      "reasoning": 61.0,
      "stress": 31.5,
      "valence": "Low",
      "arousal": "Low"
    }
  ]
}

past_sessions[i] must correspond to past_targets[i] as they shall represent the same session.

Single-session vs. multi-session​

Single session (no history): The model makes a prediction based solely on the current night's sleep and the day's biometrics. This gives a solid baseline prediction, especially when demographic factors are well-specified.

Multi-session (with history): Providing past sessions enables the model to account for individual baseline variation. For example, a user who habitually scores 40 on reasoning will be interpreted differently from one who typically scores 70, even with identical raw biometrics. Up to 5 past sessions are accepted, and more recent sessions carry more weight in the model's interpretation.

Next steps​