<!--
{
  "availability" : [
    "iOS: 17.0.0 -",
    "iPadOS: 17.0.0 -",
    "macCatalyst: 17.0.0 -",
    "macOS: 14.0.0 -",
    "tvOS: 17.0.0 -",
    "visionOS: 1.0.0 -",
    "watchOS: 10.0.0 -"
  ],
  "documentType" : "symbol",
  "framework" : "CloudKit",
  "identifier" : "/documentation/CloudKit/CKSyncEngineState",
  "metadataVersion" : "0.1.0",
  "role" : "Class",
  "symbol" : {
    "kind" : "Class",
    "modules" : [
      "CloudKit"
    ],
    "preciseIdentifier" : "c:objc(cs)CKSyncEngineState"
  },
  "title" : "CKSyncEngineState"
}
-->

# CKSyncEngineState

An object that manages the sync engine’s state.

```
@interface CKSyncEngineState : NSObject
```

## Overview

To reliably and consistently sync your app’s data, a sync engine keeps a record of several important pieces of data, such as server changes tokens (for databases and record zones), subscription identifiers, the most recent [`userRecordID`](/documentation/CloudKit/CKUserIdentity/userRecordID), and so on.
This class automatically manages that state on behalf of your app, but there are certain elements you can modify.
For example, you control the list of pending changes to send to the iCloud servers and manipulate that list using the [`addPendingDatabaseChanges:`](/documentation/CloudKit/CKSyncEngineState/addPendingDatabaseChanges:) and [`addPendingRecordZoneChanges:`](/documentation/CloudKit/CKSyncEngineState/addPendingRecordZoneChanges:) methods.
If there aren’t any scheduled sync operations when you invoke these methods, the engine automatically schedules one.

An engine’s state changes periodically and, when it does, the sync engine dispatches an event of type  [`CKSyncEngineStateUpdateEvent`](/documentation/CloudKit/CKSyncEngineStateUpdateEvent) to your delegate.
The event contains an instance of [`CKSyncEngineStateSerialization`](/documentation/CloudKit/CKSyncEngineStateSerialization) and, on receipt of such an event, it’s your responsibility to persist the serialized state to disk so that it’s available across app launches.
On the next initialization of the sync engine, you provide the most recently persisted state as part of the engine’s configuration.
For more information, see [`initWithDatabase:stateSerialization:delegate:`](/documentation/CloudKit/CKSyncEngineConfiguration/initWithDatabase:stateSerialization:delegate:).

## Topics

### Accessing pending changes

[`hasPendingUntrackedChanges`](/documentation/CloudKit/CKSyncEngineState/hasPendingUntrackedChanges)

A Boolean value that indicates whether there are pending changes that the sync engine is unaware of.

[`pendingDatabaseChanges`](/documentation/CloudKit/CKSyncEngineState/pendingDatabaseChanges)

A list of database changes that the sync engine has yet to send to the iCloud servers.

[`pendingRecordZoneChanges`](/documentation/CloudKit/CKSyncEngineState/pendingRecordZoneChanges)

A list of record zone changes that the sync engine has yet to send to the iCloud servers.

### Modifying pending changes

[`addPendingDatabaseChanges:`](/documentation/CloudKit/CKSyncEngineState/addPendingDatabaseChanges:)

Adds the specified database changes to the state.

[`removePendingDatabaseChanges:`](/documentation/CloudKit/CKSyncEngineState/removePendingDatabaseChanges:)

Removes the specified database changes from the state.

[`CKSyncEnginePendingZoneDelete`](/documentation/CloudKit/CKSyncEnginePendingZoneDelete)

An object that describes an unsent record zone deletion.

[`CKSyncEnginePendingZoneSave`](/documentation/CloudKit/CKSyncEnginePendingZoneSave)

An object that describes an unsent record zone modification.

[`CKSyncEnginePendingDatabaseChange`](/documentation/CloudKit/CKSyncEnginePendingDatabaseChange)

An object that describes an unsent database modification.

[`addPendingRecordZoneChanges:`](/documentation/CloudKit/CKSyncEngineState/addPendingRecordZoneChanges:)

Adds the specified record zone changes to the state.

[`removePendingRecordZoneChanges:`](/documentation/CloudKit/CKSyncEngineState/removePendingRecordZoneChanges:)

Removes the specified record zone changes from the state.

[`CKSyncEnginePendingRecordZoneChange`](/documentation/CloudKit/CKSyncEnginePendingRecordZoneChange)

An object that describes an unsent record modification.


---

Copyright &copy; 2026 Apple Inc. All rights reserved. | [Terms of Use](https://www.apple.com/legal/internet-services/terms/site.html) | [Privacy Policy](https://www.apple.com/privacy/privacy-policy)