---
title: "Fetch Record Zone Changes"
method: POST
path: "/database/{version}/{container}/{environment}/{database}/changes/zone"
tags: ["Zones"]
---

# Fetch Record Zone Changes

`POST /database/{version}/{container}/{environment}/{database}/changes/zone`

Get the records that changed within one or more record zones relative to each zone's sync token. Intended for custom zones. Each entry in the response `zones` array is either a per-zone success result or a per-zone error.

## Path parameters

- `version` string, required — Protocol version
- `container` string, required — Container ID (begins with "iCloud.")
- `environment` 'development' | 'production', required — Container environment
- `database` 'public' | 'private' | 'shared', required — Database scope

## Request body

- object
  - `zones` RecordZoneChangesRequestZone[], required — A zone request dictionary for each zone to fetch record changes from. Per-zone values override the top-level values in this request.
    - `zoneID` ZoneID, required
      - `zoneName` string
      - `ownerName` string
    - `syncToken` string — Identifies a point in this zone's change history. Omit on the initial fetch.
    - `reverse` boolean — Whether the changes are returned in reverse order.
    - `desiredKeys` string[] — Record field names limiting the fields returned per changed record.
    - `numberAsStrings` boolean — Whether number fields should be represented as strings.
    - `resultsLimit` integer — The maximum number of records to fetch for this zone.
    - `desiredRecordTypes` string[] — Record-type names limiting the change feed for this zone.
  - `reverse` boolean — Whether the changes are returned in reverse order.
  - `desiredKeys` string[] — Record field names limiting the fields returned per changed record. Omit to fetch all fields.
  - `numberAsStrings` boolean — Whether number fields should be represented as strings. Defaults to `false`.
  - `resultsLimit` integer — The maximum number of records to fetch. Defaults to the maximum allowed in a request.
  - `desiredRecordTypes` string[] — Record-type names limiting the change feed to specific record types. Omit to fetch changes from all record types.

## Response `200`

Record zone changes retrieved successfully

- RecordZoneChangesResponse — Response body of `changes/zone` (Fetching Record Zone Changes). Each entry in `zones` is either a Zone Record Fetch dictionary (success) or a Zone Record Fetch Error dictionary (failure), per Apple's reference.
  - `zones` union[]
    - union
      - ZoneFetchFailure — Per-zone error returned inline in the `zones` array of a 200 zone response (`changes/database`, `changes/zone`, `zones/modify`). Mirrors `RecordOperationFailure` for records, but keyed by `zoneID`.
        - `zoneID` ZoneID
          - `zoneName` string
          - `ownerName` string
        - `serverErrorCode` 'ACCESS_DENIED' | 'ATOMIC_ERROR' | 'AUTHENTICATION_FAILED' | 'AUTHENTICATION_REQUIRED' | 'BAD_REQUEST' | 'CONFLICT' | 'EXISTS' | 'INTERNAL_ERROR' | 'NOT_FOUND' | 'QUOTA_EXCEEDED' | 'THROTTLED' | 'TRY_AGAIN_LATER' | 'VALIDATING_REFERENCE_ERROR' | 'ZONE_NOT_FOUND', required — The CloudKit server error code returned in a per-item failure entry (record or subscription) inline in a 200 modify/lookup response. Shared by `RecordOperationFailure` and `SubscriptionOperationFailure` via `OperationFailureCommon`. Distinct from `ErrorResponse`'s `serverErrorCode`, which carries a broader set of codes for top-level 4xx/5xx HTTP failures.
        - `reason` string — A string indicating the reason for the error.
        - `retryAfter` integer — Suggested seconds to wait before retrying. Absent if not retryable.
        - `uuid` string — A unique identifier for this error.
        - `redirectURL` string — Redirect URL for sign-in; present when serverErrorCode is AUTHENTICATION_REQUIRED.
      - RecordZoneChangesZoneResult — A successful per-zone result of `changes/zone`: the records that changed in that zone plus that zone's own sync token and `moreComing` flag.
        - `zoneID` ZoneID
          - `zoneName` string
          - `ownerName` string
        - `records` RecordResponse[]
          - `recordName` string — The unique identifier for the record
          - `recordType` string — The record type (schema name)
          - `recordChangeTag` string — Change tag for optimistic concurrency control
          - `fields` object — Record fields with their values and optional type information
          - `created` RecordTimestamp — Timestamp information for record creation or modification
            - `timestamp` number — Unix timestamp in milliseconds
            - `userRecordName` string — Record name of the user who performed the action
          - `modified` RecordTimestamp — Timestamp information for record creation or modification
            - `timestamp` number — Unix timestamp in milliseconds
            - `userRecordName` string — Record name of the user who performed the action
          - `deleted` boolean — Whether the record was deleted
          - `shortGUID` string — The short GUID of a shared record. Present only on records that have been shared (see `createShortGUID` on the request side).
          - `share` ShareReference — A reference to the `cloudKit.share` record governing a shared record.
            - `recordName` string
          - `publicPermission` 'NONE' | 'READ_ONLY' | 'READ_WRITE' | 'UNKNOWN' — The public read/write permissions of a shared record. Present on `cloudKit.share` records.
          - `participants` ShareParticipant[] — The participants in a shared record. Present on `cloudKit.share` records.
            - `userIdentity` UserIdentity — A user identity returned by discover endpoints
              - …
            - `permission` 'NONE' | 'READ_ONLY' | 'READ_WRITE' | 'UNKNOWN' — The participant's read and write permissions.
            - `type` 'OWNER' | 'ADMINISTRATOR' | 'USER' | 'PUBLIC_USER' | 'UNKNOWN' — The type of participant.
            - `acceptanceStatus` 'INVITED' | 'ACCEPTED' | 'REMOVED' | 'UNKNOWN' — The status of the participant accepting the shared record.
          - `owner` ShareParticipant — A participant in a shared record.
            - `userIdentity` UserIdentity — A user identity returned by discover endpoints
              - …
            - `permission` 'NONE' | 'READ_ONLY' | 'READ_WRITE' | 'UNKNOWN' — The participant's read and write permissions.
            - `type` 'OWNER' | 'ADMINISTRATOR' | 'USER' | 'PUBLIC_USER' | 'UNKNOWN' — The type of participant.
            - `acceptanceStatus` 'INVITED' | 'ACCEPTED' | 'REMOVED' | 'UNKNOWN' — The status of the participant accepting the shared record.
          - `currentUserParticipant` ShareParticipant — A participant in a shared record.
            - `userIdentity` UserIdentity — A user identity returned by discover endpoints
              - …
            - `permission` 'NONE' | 'READ_ONLY' | 'READ_WRITE' | 'UNKNOWN' — The participant's read and write permissions.
            - `type` 'OWNER' | 'ADMINISTRATOR' | 'USER' | 'PUBLIC_USER' | 'UNKNOWN' — The type of participant.
            - `acceptanceStatus` 'INVITED' | 'ACCEPTED' | 'REMOVED' | 'UNKNOWN' — The status of the participant accepting the shared record.
        - `syncToken` string — Identifies a point in this zone's change history.
        - `moreComing` boolean — Whether there are more changes to request for this zone using the returned `syncToken`.

## Other responses

- `400` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `401` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `403` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `404` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `409` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `412` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `413` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `421` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `429` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `500` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)
- `503` — Error response shared by all endpoints. The body schema is the same for every 4xx/5xx status code; the HTTP status code itself disambiguates which CloudKit failure occurred. See Apple's CloudKit Web Services Error Codes documentation for the full code → status mapping: - 400 BadRequest (BAD_REQUEST, ATOMIC_ERROR) - 401 Unauthorized (AUTHENTICATION_FAILED) - 403 Forbidden (ACCESS_DENIED) - 404 NotFound (NOT_FOUND, ZONE_NOT_FOUND) - 409 Conflict (CONFLICT, EXISTS) - 412 PreconditionFailed (VALIDATING_REFERENCE_ERROR) - 413 RequestEntityTooLarge (QUOTA_EXCEEDED) - 421 UnprocessableEntity (AUTHENTICATION_REQUIRED) - 429 TooManyRequests (THROTTLED) - 500 InternalServerError (INTERNAL_ERROR) - 503 ServiceUnavailable (TRY_AGAIN_LATER)

## Changes

- **2026-08-28** `0beaa734d18c` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/changes/database/:version/:container/:environment/:database/changes/zone/post.md)

---

[API](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api.md) · [All operations](https://skmtc.dev/brightdigit/apis/apple-cloudkit-web-services-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/brightdigit/apple-cloudkit-web-services-api/revisions/db45a101c485/schema)