Fetch intra-day detail data for a whole organization or company (v2)

curl --request GET \
  --url https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "_time": "2025-02-21T08:00:00+00:00",
    "uid": "user123",
    "API_ver": "2.0.0",
    "fw_ver": 1022,
    "health_hr": 72,
    "health_hrv": 45,
    "health_spo2": 98,
    "health_stress": 25,
    "health_T": 33.5,
    "health_lf": 120.5,
    "health_hf": 250.3,
    "sleep_hr": 58,
    "sleep_hrv": 52,
    "sleep_spo2": 97,
    "sleep_stage": 1,
    "sleep_odi": 2,
    "sleep_respiration": 14,
    "activity_steps": 150,
    "activity_calorie": 12,
    "activity_zcm": 128,
    "activity_pim": 256,
    "activity_sleep_awake": 5
  }
]

{
  "error": "bad-request",
  "error_msg": "The range of start_day and end_day should not exceed 31 days."
}

{
  "error": "http-error",
  "error_msg": "Invalid authentication credentials. <reason>"
}

{
  "error": "forbidden",
  "error_msg": "Not enough permission"
}

{
  "error": "not-found",
  "error_msg": "Org '<org_id>' not found"
}

{
  "error": "unprocessable-entity",
  "error_msg": "body.<field>: <validation message>"
}

{
  "error": "rate-limited",
  "error_msg": "Rate limit exceeded. Retry after <n> seconds."
}

{
  "error": "internal-server-error",
  "error_msg": "Failed to fetch data: <error_message>"
}

Data (v2)

Fetch intra-day detail data for a whole organization or company (v2)

Fetch intra-day detail records (SX_Detail_Prod) with standardized field names for every reachable member of an organization or a company.

Parameters

company_id / org_id (query) - the scope to answer for. At least one is required; which of them a caller may name depends on its role, described below.
start_day / end_day (query, optional) - YYYY-MM-DD, both inclusive. An ISO 8601 value with an explicit time is also accepted; a time-valued end_day remains the exclusive end instant. The range must not exceed 31 days.
uid_list (query, optional) - restrict the answer to these members, at most 100. They must all be inside the resolved scope.
page (query, optional, default 0) - 0-indexed page of 100 members, used when uid_list is not given.
format (query, optional) - json (default) or csv.

Response

200 with format=json returns an array of intra-day records across the users the request resolves to.
200 with format=csv returns the same rows as a file download.
A request that resolves to no rows is still a 200, carrying msg: No data found.

Errors

Status	Condition
400	`start_day` or `end_day` is neither `YYYY-MM-DD` nor an ISO 8601 datetime, `end_day` is earlier than `start_day`, the range is longer than the number of users allows, or none of `company_id`, `org_id` and `uid_list` was given
404	The `company_id` or `org_id` names nothing that exists

Authorization

Scheme: Authorization: Bearer <idToken> or soxai-api-key: <api key>.
Admin, PartnerAdmin or OrgAdmin. Which scope applies is decided by the arguments, so this endpoint resolves a set of readable uids rather than answering a single yes or no.
Admin must name a company_id or an org_id and reaches either. PartnerAdmin reaches its own company, and an org_id it names only narrows that company. OrgAdmin reaches only its own organization and is refused a company_id.
A caller holding both PartnerAdmin and OrgAdmin is confined to the intersection of the two.
Existence is checked after authorization, so a scoped caller is told “not yours” before it can learn whether a company or organization exists.

Response fields

SX_Detail_Prod (v2 output)

Field	Unit	Description
`_time`	datetime	Time: Data timestamp
`uid`	string	User ID: User identifier
`API_ver`	string	API Version: API version in effect at the time of the record
`fw_ver`	string	Firmware Version: Raw FW_version aligned onto the detail time series
`activity_zcm`		Activity - Zero Crossing Count: Raw zc field. Unit and value details are not documented in the schema list
`activity_pim`		Activity - Activity Amount: Raw acti field. Unit and value details are not documented in the schema list
`activity_jerk`		Activity - Jerk: Listed as an output column, but nothing in the repository writes it, so it does not appear in the response
`activity_mets`	METs	Activity - METs: Physical activity intensity in multiples of the resting metabolic rate
`activity_sleep_awake`		Activity - Sleep or Awake: Raw sleep_f field. Unit and value details are not documented in the schema list
`activity_calorie`	kcal	Activity - Calories Burned: Calories burned
`activity_steps`	count	Activity - Steps: Number of steps
`activity_confirm`	flag	Activity - Confirmation Flag: Data confirmation flag (1: confirmed, 0: unconfirmed)
`activity_type`	category	Activity - Type: Activity type (0: resting, 1: walking, 2: running, 3: other, 9: unknown)
`activity_strength`	ratio	Activity - Intensity: Index of activity intensity
`activity_act_mlc`	category	Activity - Edge Processing Data: Edge processing data (act_mlc)
`health_T`	°C	Health - Skin Temperature: Skin temperature
`health_cbt`	°C	Health - Core Body Temperature: Always null. Core body temperature is not yet stored in the database
`health_hr`	bpm	Health - Heart Rate: Average heart rate
`health_hrv`	ms	Health - Heart Rate Variability: Heart rate variability (RMSSD)
`health_lf`		Health - LF: Raw LF field, the low frequency component of heart rate variability. Unit and value details are not documented in the schema list
`health_hf`		Health - HF: health_lf divided by the raw lf_hf ratio; null where lf_hf is 0. Unit and value details are not documented in the schema list
`health_spo2`	%	Health - Blood Oxygen Saturation: Blood oxygen saturation
`health_stress`	pt	Health - Stress Level: Stress level
`health_hr_dB`		Health - Heart Rate Signal Level: Raw HR_dB field. Unit and value details are not documented in the schema list
`sleep_hr`	bpm	Sleep - Heart Rate: Heart rate during sleep
`sleep_hrv`	ms	Sleep - Heart Rate Variability: Heart rate variability during sleep (RMSSD)
`sleep_spo2`	%	Sleep - SpO2: health_spo2 restricted to epochs that are asleep and not awake; null on every other row
`sleep_stage`	category	Sleep - Stage (4 Categories): Sleep stage (0: deep sleep, 1: light sleep, 2: REM, 3: awake or undetermined)
`sleep_stage_1min`	category	Sleep - 1-Minute Stage (4 Categories): Sleep stage for each minute, one digit per minute joined into an integer (0: deep sleep, 1: light sleep, 2: REM, 3: awake or undetermined)
`sleep_odi`	index	Sleep - ODI: 3% oxygen desaturation index (ODI)
`sleep_respiration`	breath/min	Sleep - Respiratory Rate: Respiratory rate
`utc_offset_mins`	mins	UTC Offset: Time difference from UTC in minutes

GET

api

DailyDetailDataForOrg

Fetch intra-day detail data for a whole organization or company (v2)

curl --request GET \
  --url https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://web-api.dev.soxai.site/api/v2/DailyDetailDataForOrg', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

[
  {
    "_time": "2025-02-21T08:00:00+00:00",
    "uid": "user123",
    "API_ver": "2.0.0",
    "fw_ver": 1022,
    "health_hr": 72,
    "health_hrv": 45,
    "health_spo2": 98,
    "health_stress": 25,
    "health_T": 33.5,
    "health_lf": 120.5,
    "health_hf": 250.3,
    "sleep_hr": 58,
    "sleep_hrv": 52,
    "sleep_spo2": 97,
    "sleep_stage": 1,
    "sleep_odi": 2,
    "sleep_respiration": 14,
    "activity_steps": 150,
    "activity_calorie": 12,
    "activity_zcm": 128,
    "activity_pim": 256,
    "activity_sleep_awake": 5
  }
]

{
  "error": "bad-request",
  "error_msg": "The range of start_day and end_day should not exceed 31 days."
}

{
  "error": "http-error",
  "error_msg": "Invalid authentication credentials. <reason>"
}

{
  "error": "forbidden",
  "error_msg": "Not enough permission"
}

{
  "error": "not-found",
  "error_msg": "Org '<org_id>' not found"
}

{
  "error": "unprocessable-entity",
  "error_msg": "body.<field>: <validation message>"
}

{
  "error": "rate-limited",
  "error_msg": "Rate limit exceeded. Retry after <n> seconds."
}

{
  "error": "internal-server-error",
  "error_msg": "Failed to fetch data: <error_message>"
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

company_id

string

Company ID to filter data. Accepted from an admin, and from a PartnerAdmin naming its own company. An OrgAdmin is refused with 403.

Example:

"company123"

org_id

string

Org ID to filter data. Accepted from an admin, from a PartnerAdmin naming an org its company owns, and from an OrgAdmin naming its own org.

Example:

"org123"

start_day

string

Start date in YYYY-MM-DD format (e.g., 2025-01-01T00:00:00+09:00). Range of start_day and end_day should not exceed 31 days.

Example:

"2025-01-01T00:00:00+09:00"

end_day

string

End date in YYYY-MM-DD format (inclusive), or a datetime that is the exclusive end instant (e.g., 2025-02-01T00:00:00+09:00 to read through 2025-01-31 JST). Range of start_day and end_day should not exceed 31 days.

Example:

"2025-02-01T00:00:00+09:00"

format

enum<string>

default:json

json (default) returns the records inline; csv returns a file download.

Available options:

csv,

json

Example:

"json"

uid_list

string[]

Optional list of user IDs to filter. Must all belong to the org. Max 100 UIDs.

Example:

["user123", "user456"]

page

integer

default:0

0-indexed page number when org has more than 100 users and uid_list is not provided.

Required range: x >= 0

Example:

0

Response

Daily detail data fetched successfully with renamed fields. A json request answers with an array, wrapped in pagination / data keys when the org needs more than one page; when nothing matches, the body is the No data found message. format=csv answers with a file download.

Pagination counts eligible users, not measurement records. pagination contains total_users, total_pages, current_page (zero-based), and page_size (100 users). For example, with 105 eligible users in total, page=1 selects the second page (the remaining 5 users) and produces metadata {"total_users":105,"total_pages":2,"current_page":1,"page_size":100}. Request another page while current_page + 1 < total_pages, regardless of record count. A non-empty uid_list disables pagination. A page without measurements can return {"msg":"No data found"} without metadata, even if more pages exist. Use a previously obtained total_pages or explicit uid_list batches; this message alone cannot determine the final page. An out-of-range page returns metadata and data: [].

Get started

API Reference (Sandbox)

API Reference (Production)

About

Fetch intra-day detail data for a whole organization or company (v2)

Authorizations

Query Parameters

Response