> ## Documentation Index
> Fetch the complete documentation index at: https://docs.junction.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Summary

> Retrieve processed sleep summary data for a specific user, including duration, efficiency, and quality scores.

<RequestExample>
  ```bash cURL theme={null}
  curl --request GET \
       --url {{BASE_URL}}/v2/summary/sleep/{user_id}?start_date={{START_DATE}}&end_date={{END_DATE}} \
       --header 'Accept: application/json' \
       --header 'x-vital-api-key: <API_KEY>'
  ```

  ```python Python theme={null}
  from junction import Junction
  from junction.environment import JunctionEnvironment

  client = Junction(
      api_key="YOUR_API_KEY",
      environment=JunctionEnvironment.SANDBOX,
  )

  data = client.sleep.get(
      "<user_id>",
      start_date="2021-01-01",
      end_date="2021-01-02",
  )
  ```

  ```typescript TypeScript theme={null}
  import { JunctionClient, JunctionEnvironment } from "@junction-api/sdk";

  const client = new JunctionClient({
      apiKey: "YOUR_API_KEY",
      environment: JunctionEnvironment.Sandbox,
  });

  const data = await client.sleep.get({
      userId: "<user_id>",
      startDate: "2021-01-01",
      endDate: "2021-01-02",
  });
  ```

  ```java Java theme={null}
  import com.junction.api.Junction;
  import com.junction.api.core.Environment;
  import com.junction.api.resources.sleep.requests.GetSleepRequest;

  Junction client = Junction.builder()
      .apiKey("YOUR_API_KEY")
      .environment(Environment.SANDBOX)
      .build();

  var data = client.sleep().get(
      "<user_id>",
      GetSleepRequest.builder()
          .startDate("2021-01-01")
          .endDate("2021-01-02")
          .build()
  );
  ```

  ```go Go theme={null}
  import (
      "context"

      junction "github.com/junction-api/junction-go"
      "github.com/junction-api/junction-go/client"
      "github.com/junction-api/junction-go/option"
  )

  c := client.NewClient(
      option.WithApiKey("YOUR_API_KEY"),
      option.WithBaseURL(junction.Environments.Sandbox),
  )

  endDate := "2021-01-02"
  response, err := c.Sleep.Get(context.TODO(), &junction.GetSleepRequest{
      UserId:    "<user_id>",
      StartDate: "2021-01-01",
      EndDate:   &endDate,
  })
  if err != nil {
      return err
  }
  fmt.Printf("Received data %s\n", response)
  ```
</RequestExample>


## OpenAPI

````yaml GET /v2/summary/sleep/{user_id}
openapi: 3.1.0
info:
  title: Junction API
  description: https://docs.junction.com/
  version: 0.4.495
servers:
  - url: https://api.us.junction.com
    x-fern-server-name: Production
  - url: https://api.eu.junction.com
    x-fern-server-name: ProductionEU
  - url: https://api.sandbox.us.junction.com
    x-fern-server-name: Sandbox
  - url: https://api.sandbox.eu.junction.com
    x-fern-server-name: SandboxEU
security:
  - apiKeyAuth: []
paths:
  /v2/summary/sleep/{user_id}:
    get:
      tags:
        - summary
      summary: Get User Sleep
      description: Get sleep summary for user_id
      operationId: get_user_sleep_v2_summary_sleep__user_id__get
      parameters:
        - name: user_id
          in: path
          required: true
          schema:
            type: string
            format: uuid
            title: >-
              User id returned by vital create user id request. This id should
              be stored in your database against the user and used for all
              interactions with the vital api.
        - name: provider
          in: query
          required: false
          schema:
            type: string
            description: Provider oura/strava etc
            default: ''
            title: Provider
          description: Provider oura/strava etc
        - name: start_date
          in: query
          required: true
          schema:
            type: string
            description: >-
              Date from in YYYY-MM-DD or ISO formatted date time. If a date is
              provided without a time, the time will be set to 00:00:00
            title: Start Date
          description: >-
            Date from in YYYY-MM-DD or ISO formatted date time. If a date is
            provided without a time, the time will be set to 00:00:00
        - name: end_date
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: >-
              Date to YYYY-MM-DD or ISO formatted date time. If a date is
              provided without a time, the time will be set to 23:59:59
            title: End Date
          description: >-
            Date to YYYY-MM-DD or ISO formatted date time. If a date is provided
            without a time, the time will be set to 23:59:59
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ClientSleepResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    ClientSleepResponse:
      properties:
        sleep:
          items:
            $ref: '#/components/schemas/ClientFacingSleep'
          type: array
          title: Sleep
      type: object
      required:
        - sleep
      title: Sleep Data
      example:
        sleep:
          - average_hrv: 78
            awake: 2400
            bedtime_start: '2023-02-27T12:31:24+00:00'
            bedtime_stop: '2023-02-27T12:31:24+00:00'
            calendar_date: '2023-02-27'
            created_at: '2023-02-27T20:31:24+00:00'
            date: '2023-02-27T12:31:24+00:00'
            deep: 2400
            duration: 28800
            efficiency: 0.97
            hr_average: 50
            hr_lowest: 43
            id: e2e0eb04-6641-4858-9de5-649efb41b346
            latency: 1000
            light: 2400
            recovery_readiness_score: 82
            rem: 2400
            respiratory_rate: 14
            skin_temperature: 36.5
            source:
              device_id: 550e8400-e29b-41d4-a716-446655440000
              provider: oura
              type: unknown
            temperature_delta: -0.2
            timezone_offset: 2400
            total: 28800
            updated_at: '2023-02-28T01:22:38+00:00'
            user_id: 1449752e-0d8a-40e0-9206-91ab099b2537
    HTTPValidationError:
      properties:
        detail:
          title: Detail
      type: object
      title: HTTPValidationError
    ClientFacingSleep:
      properties:
        id:
          type: string
          format: uuid
          title: Id
        user_id:
          type: string
          format: uuid
          title: User Id
          description: >-
            User id returned by vital create user request. This id should be
            stored in your database against the user and used for all
            interactions with the vital api.
        date:
          type: string
          format: date-time
          title: Date
          description: >-
            Date of the specified record, formatted as ISO8601 datetime string
            in UTC 00:00. Deprecated in favour of calendar_date.
          deprecated: true
        calendar_date:
          type: string
          format: date
          title: Calendar Date
          description: >-
            Date of the sleep summary in the YYYY-mm-dd format. This generally
            matches the sleep end date.
        bedtime_start:
          type: string
          format: date-time
          title: Bedtime Start
          description: UTC Time when the sleep period started
        bedtime_stop:
          type: string
          format: date-time
          title: Bedtime Stop
          description: UTC Time when the sleep period ended
        type:
          $ref: '#/components/schemas/SleepType'
          description: >-

            `long_sleep`: >=3 hours of sleep;

            `short_sleep`: <3 hours of sleep;

            `acknowledged_nap`: User-acknowledged naps, typically under 3 hours
            of sleep;

            `unknown`: The sleep session recording is ongoing.
             ℹ️ This enum is non-exhaustive.
        timezone_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timezone Offset
          description: >-
            Timezone offset from UTC as seconds. For example, EEST (Eastern
            European Summer Time, +3h) is 10800. PST (Pacific Standard Time,
            -8h) is -28800::seconds
        duration:
          type: integer
          title: Duration
          description: >-
            Total duration of the sleep period (sleep.duration =
            sleep.bedtime_end - sleep.bedtime_start)::seconds
        total:
          type: integer
          title: Total
          description: >-
            Total amount of sleep registered during the sleep period
            (sleep.total = sleep.rem + sleep.light + sleep.deep)::seconds
        awake:
          type: integer
          title: Awake
          description: >-
            Total amount of awake time registered during the sleep
            period::seconds
        light:
          type: integer
          title: Light
          description: >-
            Total amount of light sleep registered during the sleep
            period::seconds
        rem:
          type: integer
          title: Rem
          description: >-
            Total amount of REM sleep registered during the sleep period,
            minutes::seconds
        deep:
          type: integer
          title: Deep
          description: >-
            Total amount of deep (N3) sleep registered during the sleep
            period::seconds
        score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Score
          description: >-
            A value between 1 and 100 representing how well the user slept.
            Currently only available for Withings, Oura, Whoop and
            Garmin::scalar
        recovery_readiness_score:
          anyOf:
            - type: integer
            - type: 'null'
          title: Recovery Readiness Score
          description: >-
            A value between 0 and 100 representing the provider's
            recovery/readiness proxy. Currently sourced from Oura readiness
            score, Whoop recovery score, and Ultrahuman recovery::scalar
        hr_lowest:
          anyOf:
            - type: integer
            - type: 'null'
          title: Hr Lowest
          description: >-
            The lowest heart rate (5 minutes sliding average) registered during
            the sleep period::beats per minute
        hr_average:
          anyOf:
            - type: integer
            - type: 'null'
          title: Hr Average
          description: >-
            The average heart rate registered during the sleep period::beats per
            minute
        hr_resting:
          anyOf:
            - type: integer
            - type: 'null'
          title: Hr Resting
          description: Resting heart rate recorded during a sleep session::bpm
        efficiency:
          anyOf:
            - type: number
            - type: 'null'
          title: Efficiency
          description: >-
            Sleep efficiency is the percentage of the sleep period spent asleep
            (100% * sleep.total / sleep.duration)::perc
        latency:
          anyOf:
            - type: integer
            - type: 'null'
          title: Latency
          description: >-
            Detected latency from bedtime_start to the beginning of the first
            five minutes of persistent sleep::seconds
        temperature_delta:
          anyOf:
            - type: number
            - type: 'null'
          title: Temperature Delta
          description: >-
            Skin temperature deviation from the long-term temperature
            average::celcius
        skin_temperature:
          anyOf:
            - type: number
            - type: 'null'
          title: Skin Temperature
          description: The skin temperature::celcius
        hr_dip:
          anyOf:
            - type: number
            - type: 'null'
          title: Hr Dip
          description: >-
            Sleeping Heart Rate Dip is the percentage difference between your
            average waking heart rate and your average sleeping heart rate. In
            health studies, a greater "dip" is typically seen as a positive
            indicator of overall health. Currently only available for
            Garmin::perc
        state:
          anyOf:
            - $ref: '#/components/schemas/SleepSummaryState'
            - type: 'null'
          description: >-
            Some providers can provide updates to the sleep summary hours after
            the sleep period has ended. This field indicates the state of the
            sleep summary. For example, TENTATIVE means the summary is an intial
            prediction from the provider and can be subject to change. Currently
            only available for Garmin and EightSleep::str ℹ️ This enum is
            non-exhaustive.
        average_hrv:
          anyOf:
            - type: number
            - type: 'null'
          title: Average Hrv
          description: >-
            The average heart rate variability registered during the sleep
            period::rmssd
        respiratory_rate:
          anyOf:
            - type: number
            - type: 'null'
          title: Respiratory Rate
          description: Average respiratory rate::breaths per minute
        source:
          $ref: '#/components/schemas/ClientFacingSource'
          description: Source the data has come from.
        sleep_stream:
          anyOf:
            - $ref: '#/components/schemas/ClientFacingSleepStream'
            - type: 'null'
          deprecated: true
        created_at:
          type: string
          format: date-time
          title: Created At
        updated_at:
          type: string
          format: date-time
          title: Updated At
      type: object
      required:
        - id
        - user_id
        - date
        - calendar_date
        - bedtime_start
        - bedtime_stop
        - type
        - duration
        - total
        - awake
        - light
        - rem
        - deep
        - source
        - created_at
        - updated_at
      title: Sleep Data
      example:
        average_hrv: 78
        awake: 2400
        bedtime_start: '2023-02-27T12:31:24+00:00'
        bedtime_stop: '2023-02-27T12:31:24+00:00'
        calendar_date: '2023-02-27'
        created_at: '2023-02-27T20:31:24+00:00'
        date: '2023-02-27T12:31:24+00:00'
        deep: 2400
        duration: 28800
        efficiency: 0.97
        hr_average: 50
        hr_lowest: 43
        id: e2e0eb04-6641-4858-9de5-649efb41b346
        latency: 1000
        light: 2400
        recovery_readiness_score: 82
        rem: 2400
        respiratory_rate: 14
        skin_temperature: 36.5
        source:
          device_id: 550e8400-e29b-41d4-a716-446655440000
          provider: oura
          type: unknown
        temperature_delta: -0.2
        timezone_offset: 2400
        total: 28800
        updated_at: '2023-02-28T01:22:38+00:00'
        user_id: 1449752e-0d8a-40e0-9206-91ab099b2537
    SleepType:
      type: string
      enum:
        - long_sleep
        - short_sleep
        - acknowledged_nap
        - unknown
      title: SleepType
      description: ℹ️ This enum is non-exhaustive.
    SleepSummaryState:
      type: string
      enum:
        - tentative
        - confirmed
      title: SleepSummaryState
      description: ℹ️ This enum is non-exhaustive.
    ClientFacingSource:
      properties:
        provider:
          type: string
          title: Provider
          description: Provider slug. e.g., `oura`, `fitbit`, `garmin`.
        type:
          type: string
          title: Type
          description: >-
            The type of the data source (app or device) by which the summary or
            the timeseries data were recorded. This defaults to `unknown` when
            Vital cannot extract or infer that information
          default: unknown
        app_id:
          anyOf:
            - type: string
            - type: 'null'
          title: App Id
          description: >-
            The identifier of the app which recorded this summary. This is only
            applicable to multi-source providers like Apple Health and Android
            Health Connect.
        device_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Device Id
          description: The identifier of the device which recorded this summary.
        sport:
          anyOf:
            - type: string
            - type: 'null'
          title: Sport
          description: >

            For workout stream timeseries, this is the standard sport slug of
            the workout with which the timeseries data are associated.


            For the `distance` timeseries, this is `wheelchair_pushing` if the
            user is a wheelchair user, or `null` otherwise.


            For all summary types and non-workout timeseries, this is always
            `null`.
        workout_id:
          anyOf:
            - type: string
              format: uuid
            - type: 'null'
          title: Workout Id
          description: >

            For workout stream timeseries, this is the workout ID with which the
            timeseries data are associated.


            For all other types, this is always `null`.
        name:
          type: string
          title: Name
          description: Deprecated. Subject to removal after 1 Jan 2024.
          default: ''
          deprecated: true
        slug:
          type: string
          title: Slug
          description: >-
            Deprecated. Use `provider` instead. Subject to removal after 1 Jan
            2024.
          default: ''
          deprecated: true
        logo:
          type: string
          title: Logo
          description: Deprecated. Subject to removal after 1 Jan 2024.
          default: ''
          deprecated: true
      type: object
      required:
        - provider
      title: Source
      description: |-
        Source summarizes where a sample or a summary is sourced from.
        At minimum, the source provider is always included.
      example:
        provider: oura
        type: ring
    ClientFacingSleepStream:
      properties:
        hrv:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClientFacingHRVTimeseries'
              type: array
            - type: 'null'
          title: Hrv
          default: []
        heartrate:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClientFacingHeartRateTimeseries'
              type: array
            - type: 'null'
          title: Heartrate
          default: []
        hypnogram:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClientFacingHypnogramTimeseries'
              type: array
            - type: 'null'
          title: Hypnogram
          default: []
        respiratory_rate:
          anyOf:
            - items:
                $ref: '#/components/schemas/ClientFacingRespiratoryRateTimeseries'
              type: array
            - type: 'null'
          title: Respiratory Rate
          default: []
      type: object
      title: Sleep stream data
      example:
        heartrate:
          - id: 0
            timestamp: '2026-05-19T18:16:05.361974+00:00'
            unit: bpm
            value: 129
          - id: 1
            timestamp: '2026-05-19T18:16:35.361991+00:00'
            unit: bpm
            value: 106
          - id: 2
            timestamp: '2026-05-19T18:17:05.362007+00:00'
            unit: bpm
            value: 8
          - id: 3
            timestamp: '2026-05-19T18:17:35.362021+00:00'
            unit: bpm
            value: 11
          - id: 4
            timestamp: '2026-05-19T18:18:05.362035+00:00'
            unit: bpm
            value: 101
        hrv:
          - id: 0
            timestamp: '2026-05-19T18:16:05.361764+00:00'
            unit: rmssd
            value: 10
          - id: 1
            timestamp: '2026-05-19T18:16:35.361868+00:00'
            unit: rmssd
            value: 31
          - id: 2
            timestamp: '2026-05-19T18:17:05.361909+00:00'
            unit: rmssd
            value: 26
          - id: 3
            timestamp: '2026-05-19T18:17:35.361936+00:00'
            unit: rmssd
            value: 75
          - id: 4
            timestamp: '2026-05-19T18:18:05.361956+00:00'
            unit: rmssd
            value: 28
        hypnogram:
          - id: 0
            timestamp: '2026-05-19T18:16:05.362050+00:00'
            unit: stage
            value: -1
          - id: 1
            timestamp: '2026-05-19T18:16:35.362063+00:00'
            unit: stage
            value: 2
          - id: 2
            timestamp: '2026-05-19T18:17:05.362077+00:00'
            unit: stage
            value: -1
          - id: 3
            timestamp: '2026-05-19T18:17:35.362090+00:00'
            unit: stage
            value: 3
          - id: 4
            timestamp: '2026-05-19T18:18:05.362101+00:00'
            unit: stage
            value: 2
        respiratory_rate:
          - id: 0
            timestamp: '2026-05-19T18:16:05.362114+00:00'
            unit: bpm
            value: 25
          - id: 1
            timestamp: '2026-05-19T18:16:35.362134+00:00'
            unit: bpm
            value: 11
          - id: 2
            timestamp: '2026-05-19T18:17:05.362146+00:00'
            unit: bpm
            value: 18
          - id: 3
            timestamp: '2026-05-19T18:17:35.362158+00:00'
            unit: bpm
            value: 27
          - id: 4
            timestamp: '2026-05-19T18:18:05.362170+00:00'
            unit: bpm
            value: 23
    ClientFacingHRVTimeseries:
      properties:
        id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Id
          description: Deprecated
        timezone_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timezone Offset
          description: >-
            Time zone UTC offset in seconds. Positive offset indicates east of
            UTC; negative offset indicates west of UTC; and null indicates the
            time zone information is unavailable at source.
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Type is always null for this resource.
        unit:
          type: string
          title: Unit
          description: Measured in rmssd.
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: The timestamp of the measurement.
        value:
          type: number
          title: Value
          description: HRV calculated using rmssd during sleep
      type: object
      required:
        - unit
        - timestamp
        - value
      title: ClientFacingHRVTimeseries
      example:
        timestamp: '2023-02-13T14:30:52+00:00'
        unit: rmssd
        value: 48
    ClientFacingHeartRateTimeseries:
      properties:
        id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Id
          description: Deprecated
        timezone_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timezone Offset
          description: >-
            Time zone UTC offset in seconds. Positive offset indicates east of
            UTC; negative offset indicates west of UTC; and null indicates the
            time zone information is unavailable at source.
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Type is always null for this resource.
        unit:
          type: string
          title: Unit
          description: Measured in bpm.
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: The timestamp of the measurement.
        value:
          type: number
          title: Value
          description: Heart rate in bpm
      type: object
      required:
        - unit
        - timestamp
        - value
      title: ClientFacingHeartRateTimeseries
      example:
        timestamp: '2023-02-13T14:30:52+00:00'
        unit: bpm
        value: 70
    ClientFacingHypnogramTimeseries:
      properties:
        id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Id
          description: Deprecated
        timezone_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timezone Offset
          description: >-
            Time zone UTC offset in seconds. Positive offset indicates east of
            UTC; negative offset indicates west of UTC; and null indicates the
            time zone information is unavailable at source.
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Type is always null for this resource.
        unit:
          type: string
          title: Unit
          description: 'enum: 1: deep, 2: light, 3: rem, 4: awake, -1: missing_data.'
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: Depracated. The start time (inclusive) of the interval.
        start:
          type: string
          format: date-time
          title: Start
          description: The start time (inclusive) of the interval.
        end:
          type: string
          format: date-time
          title: End
          description: The end time (exclusive) of the interval.
        value:
          type: number
          title: Value
          description: >-
            Hypnogram for sleep stages {"deep": 1, "light": 2, "rem": 3,
            "awake": 4, "manual": 5, "missing_data": -1}
      type: object
      required:
        - unit
        - timestamp
        - start
        - end
        - value
      title: ClientFacingHypnogramTimeseries
      deprecated: true
      example:
        end: '2023-02-13T14:57:24+00:00'
        start: '2023-02-13T14:30:52+00:00'
        unit: stage
        value: 1
    ClientFacingRespiratoryRateTimeseries:
      properties:
        id:
          anyOf:
            - type: integer
            - type: 'null'
          title: Id
          description: Deprecated
        timezone_offset:
          anyOf:
            - type: integer
            - type: 'null'
          title: Timezone Offset
          description: >-
            Time zone UTC offset in seconds. Positive offset indicates east of
            UTC; negative offset indicates west of UTC; and null indicates the
            time zone information is unavailable at source.
        type:
          anyOf:
            - type: string
            - type: 'null'
          title: Type
          description: Type is always null for this resource.
        unit:
          type: string
          title: Unit
          description: Measured in bpm.
        timestamp:
          type: string
          format: date-time
          title: Timestamp
          description: The timestamp of the measurement.
        value:
          type: number
          title: Value
          description: Average respiratory rate::breaths per minute
      type: object
      required:
        - unit
        - timestamp
        - value
      title: ClientFacingRespiratoryRateTimeseries
      example:
        timestamp: '2023-02-13T14:30:52+00:00'
        unit: bpm
        value: 15.5
  securitySchemes:
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-vital-api-key
      description: Vital Team API Key

````