apple_device-management/mdm/commands/system.update.status.yaml

title: OS Update Status Command
description: 'Get the status of operating-system updates on a device. Removed: subscribe
  to the declarative management `softwareupdate.install-state` status item.'
payload:
  requesttype: OSUpdateStatus
  supportedOS:
    iOS:
      introduced: '9.0'
      deprecated: '26.0'
      removed: '27.0'
      accessrights: AllowAppInstallation
      supervised: true
      requiresdep: false
      sharedipad:
        mode: allowed
        devicechannel: true
        userchannel: false
      userenrollment:
        mode: forbidden
    macOS:
      introduced: 10.11.5
      deprecated: '26.0'
      removed: '27.0'
      accessrights: None
      devicechannel: true
      userchannel: false
      supervised: true
      requiresdep: false
      userenrollment:
        mode: forbidden
    tvOS:
      introduced: '12.0'
      deprecated: '26.0'
      removed: '27.0'
      accessrights: AllowAppInstallation
      devicechannel: true
      supervised: true
      requiresdep: false
    visionOS:
      introduced: n/a
    watchOS:
      introduced: n/a
  content: Queries the device for the status of software updates.
responsekeys:
- key: OSUpdateStatus
  type: <array>
  presence: required
  content: |-
    An array of dictionaries that describes the statuses of software updates. The array is empty if there are no software updates currently in progress.
    This command only returns the status for System Applications and Configuration Data updates when a Declarative Device Management `SoftwareUpdateEnforcementSpecific` configuration manages a software update.
  subkeys:
  - key: OSUpdateStatusItem
    type: <dictionary>
    presence: required
    content: A dictionary that describes the status of a software update.
    subkeys:
    - key: ProductKey
      type: <string>
      presence: required
      content: The product key that represents the update.
    - key: IsDownloaded
      type: <boolean>
      presence: required
      content: If `true`, the update has finished downloading.
    - key: DownloadPercentComplete
      type: <real>
      presence: required
      content: A floating-point number between `0.0` and `1.0` that indicates the
        download progress as a percentage.
    - key: Status
      type: <string>
      presence: required
      content: |-
        The status of the update, which is one of the following values:

        - `Idle`: The update is idle.
        - `Downloading`: The software update is downloading and subsequently preparing.
        - `Installing`: The software update is installing.
    - key: MaxDeferrals
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.3'
        tvOS:
          introduced: n/a
      type: <integer>
      presence: optional
      content: The number of times a user can defer this OS update.
    - key: DeferralsRemaining
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.3'
        tvOS:
          introduced: n/a
      type: <integer>
      presence: optional
      content: The number of remaining user deferrals for this OS update.
    - key: NextScheduledInstall
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.3'
        tvOS:
          introduced: n/a
      type: <date>
      presence: optional
      content: The date of the next attempt at installing this OS update.
    - key: PastNotifications
      supportedOS:
        iOS:
          introduced: n/a
        macOS:
          introduced: '12.3'
        tvOS:
          introduced: n/a
      type: <array>
      presence: optional
      content: The dates/times when the OS notified the user about installing this
        OS update.
      subkeys:
      - key: PastNotificationDate
        title: Past notification date
        type: <date>
notes:
- title: ''
  content: Refer to the following sections to determine supported channels and requirements,
    and to see an example request and response.
examples:
- title: Example request and response
  files:
  - request-file: examples/mdm/commands/system.update.status/example1.plist
    response-file: examples/mdm/commands/system.update.status/example2.plist