Daily Summary¶

Beta

The Daily Summary API is in beta. Behavior, field names, and enum values may change before general availability. Contact integration support before relying on it in production.

The Daily Summary API returns a single user's recorded data for one completed calendar day: steps, sleep, workouts, breath measurements, nutrition, fasting, weight, and Flex Score.

The API is read-only, and returns whole days only.

Daily Summary uses the same identity model as Alerts. Users are addressed by sharedUserId, the UUID Lumen issues per user scoped to your partnership, which you retrieve from the identity mappings endpoint and store on your side.

No PII is returned by this API. Email, name, phone, and date of birth are never transmitted.
Summaries are returned only for users who have actively granted consent for your organization in the Lumen app. If a user revokes consent, their sharedUserId stops resolving here and returns 404 USER_NOT_FOUND.

Completed days only

A day is returned only after it has ended and Lumen's daily aggregation has run for it. There is no partial-day or real-time view. See Date selection.

Date selection¶

Every call returns exactly one day.

Without date, you get the most recent completed day. In practice this is yesterday in the user's timezone.
With date, you get that exact date, provided it is complete. If it is not complete (today, a future date, or a day whose aggregation has not finished), no data is returned and the request fails with 409 DATE_NOT_COMPLETE. The API never falls back to a different day than the one you asked for.

This keeps the two access patterns unambiguous: omit date when you want "the newest thing available", pass date when you are backfilling or reconciling a specific day and need to know whether that exact day exists.

Aggregation for a given day completes by 06:00 UTC the following day, the same schedule as alert generation. A summary is final once returned. Data that syncs from the user's devices after aggregation is not backfilled into an already-aggregated day.

Get a daily summary¶

GET /partners/v1/users/{sharedUserId}/daily-summary

Headers¶

Header	Type	Required	Description
`X-Partner-Api-Key`	string	Yes	Your partner API key

Path parameters¶

Parameter	Type	Required	Description
`sharedUserId`	string (UUID)	Yes	The user's identifier within your partnership. See The sharedUserId.

Query parameters¶

Parameter	Type	Required	Description
`date`	string (`YYYY-MM-DD`)	No	The calendar date to retrieve, in the user's timezone. Must be a completed day within the last 14 days. Defaults to the most recent completed day.

cURL¶

# Most recent completed day
curl -X GET "https://{baseUrl}/partners/v1/users/5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21/daily-summary" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

# A specific completed day
curl -X GET "https://{baseUrl}/partners/v1/users/5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21/daily-summary?date=2026-08-11" \
  -H "X-Partner-Api-Key: YOUR_API_KEY"

Response (200 OK)¶

{
  "success": true,
  "data": {
    "sharedUserId": "5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21",
    "date": "2026-08-11",
    "generatedAt": "2026-08-12T06:00:00Z",

    "steps": { "value": 8412 },

    "sleep": {
      "startAt": "2026-08-10T22:47:00Z",
      "endAt": "2026-08-11T06:12:00Z",
      "durationMinutes": 445
    },

    "workouts": [
      {
        "startAt": "2026-08-11T07:35:00Z",
        "endAt": "2026-08-11T08:03:00Z",
        "type": "FUNCTIONAL",
        "durationMinutes": 28,
        "intensity": "MEDIUM"
      },
      {
        "startAt": "2026-08-11T18:10:00Z",
        "endAt": "2026-08-11T18:55:00Z",
        "type": "WEIGHTS",
        "durationMinutes": 45,
        "intensity": "HIGH"
      }
    ],

    "breath": [
      { "at": "2026-08-11T07:04:00Z", "type": "fasting", "lumenLevel": 2 },
      { "at": "2026-08-11T21:30:00Z", "type": "bedtime", "lumenLevel": 4 }
    ],

    "nutrition": { "calories": 1420, "protein": 68, "carbs": 142, "fats": 54 },

    "fasting": {
      "startAt": "2026-08-10T20:10:00Z",
      "endAt": "2026-08-11T12:05:00Z",
      "durationMinutes": 955
    },

    "weight": { "value": 78.4, "unit": "kg", "loggedAt": "2026-08-11T07:01:00Z" },
    "flex": { "value": 13.4, "loggedAt": "2026-08-11T07:04:00Z" }
  }
}

Top-level response fields¶

Field	Type	Description
`data.sharedUserId`	string (UUID)	The user this summary belongs to. Echoes the path parameter.
`data.date`	string (date)	The calendar date the summary covers, in the user's timezone.
`data.generatedAt`	string (ISO 8601)	When Lumen aggregated this summary.
`data.steps`	object \| null	Step count. See Steps.
`data.sleep`	object \| null	Main sleep session. See Sleep.
`data.workouts`	array	Workouts recorded on this date. Empty if none.
`data.breath`	array	Breath measurements taken on this date. Empty if none.
`data.nutrition`	object \| null	Logged macronutrient totals.
`data.fasting`	object \| null	Fasting window that ended on this date.
`data.weight`	object \| null	Most recent weight logged on this date.
`data.flex`	object \| null	Most recent Flex Score logged on this date.

All timestamps are UTC (ISO 8601, Z suffix). date is a calendar date in the user's own timezone, so a summary for 2026-08-11 can legitimately contain timestamps dated 2026-08-10 or 2026-08-12.

Data sections¶

Select a section below for its field schema.

StepsSleepWorkoutsBreathNutritionFastingWeightFlex

Total steps recorded for the date, from the user's connected activity source.

Field	Type	Description
`value`	integer	Total step count for the date.

The user's main sleep session for the date. A session is attributed to the date it ended, so startAt is usually on the previous evening.

Field	Type	Description
`startAt`	string (ISO 8601)	When the sleep session began.
`endAt`	string (ISO 8601)	When the sleep session ended.
`durationMinutes`	integer	Sleep duration in minutes.

Naps and secondary sessions are not included in v1.

All workouts recorded on the date, ordered by startAt. An empty array means no workout was recorded, not that data is missing.

Field	Type	Description
`startAt`	string (ISO 8601)	When the workout began.
`endAt`	string (ISO 8601)	When the workout ended.
`type`	enum	Workout category, for example `FUNCTIONAL` or `WEIGHTS`. New values may be added, see Versioning.
`durationMinutes`	integer	Workout duration in minutes.
`intensity`	enum	One of `LOW`, `MEDIUM`, `HIGH`.

All Lumen breath measurements taken on the date, ordered by at. An empty array means the user did not measure that day.

Field	Type	Description
`at`	string (ISO 8601)	When the measurement was taken.
`type`	enum	The context the measurement was taken in, for example `fasting` or `bedtime`.
`lumenLevel`	integer	The Lumen Level for this measurement, 1 to 5. Lower means the user is burning primarily fat, higher means primarily carbs.

Totals across everything the user logged on the date. Present only if the user logged food. Macronutrients are in grams.

Field	Type	Description
`calories`	integer	Total calories logged.
`protein`	integer	Total protein, in grams.
`carbs`	integer	Total carbohydrates, in grams.
`fats`	integer	Total fat, in grams.

The fasting window that ended on this date. As with sleep, startAt is commonly on the previous day.

Field	Type	Description
`startAt`	string (ISO 8601)	When the fast began.
`endAt`	string (ISO 8601)	When the fast ended.
`durationMinutes`	integer	Fast duration in minutes.

A fast still open at the end of the date is not reported until the day it ends.

The most recent weight logged on the date. This is a raw log, not the smoothed value used by WEIGHT alerts.

Field	Type	Description
`value`	number	Logged weight in `unit`.
`unit`	enum	One of `kg`, `lb`. Reflects the user's app setting.
`loggedAt`	string (ISO 8601)	When the weight was logged.

The most recent Flex Score logged on the date. Flex reflects metabolic flexibility and moves slowly, so it will not change every day.

Field	Type	Description
`value`	number	The Flex Score.
`loggedAt`	string (ISO 8601)	When the score was recorded.

Missing data¶

A completed day for which the user recorded nothing still returns 200 OK. Absence of data is expressed in the body, not as an error:

Single-value sections (steps, sleep, nutrition, fasting, weight, flex) are null.
List sections (workouts, breath) are [].

Treat null and [] as "nothing recorded", not "unavailable". A 409 is the only signal that the day itself cannot be served.

{
  "success": true,
  "data": {
    "sharedUserId": "5d3b1c44-9e8a-4f2d-9c7e-6d0a3b1f7c21",
    "date": "2026-08-11",
    "generatedAt": "2026-08-12T06:00:00Z",
    "steps": null,
    "sleep": null,
    "workouts": [],
    "breath": [],
    "nutrition": null,
    "fasting": null,
    "weight": null,
    "flex": null
  }
}

Retention¶

Daily summaries are available for the last 14 days, matching alert retention. Requesting an older date returns 409 DATE_UNAVAILABLE.

Errors¶

HTTP	code	Description
400	`INVALID_INPUT`	Malformed request (e.g. bad `date` format).
401	`UNAUTHORIZED`	Missing or invalid API key.
404	`USER_NOT_FOUND`	No user with this `sharedUserId` is accessible to your partnership. The ID is unknown, or the user has revoked consent.
409	`DATE_NOT_COMPLETE`	The requested `date` has not completed aggregation yet, or is today or in the future. Retry after 06:00 UTC on the following day.
409	`DATE_UNAVAILABLE`	The requested `date` is older than 14 days.
429	`RATE_LIMIT`	Too many requests. The `Retry-After` header indicates how long to wait.