<!--
{
  "documentType" : "article",
  "framework" : "DeviceManagement",
  "identifier" : "/documentation/DeviceManagement/retrieving-a-large-record-set",
  "metadataVersion" : "0.1.0",
  "role" : "article",
  "title" : "Retrieving a large record set"
}
-->

# Retrieving a large record set

Efficiently work with large record sets.

## Discussion

When the number of records in a response exceeds a server-controlled limit, the response is batched. You can retrieve only the records that have changed since your last query by using the `sinceModifiedToken`. Make requests in parallel to reduce the time it takes to retrieve the entire result set.

These concepts apply to the following endpoints:

- [`Get Licenses`](/documentation/DeviceManagement/Get-Licenses)
- [`Get Users`](/documentation/DeviceManagement/Get-Users-5boi1)

## Track changes

Use `sinceModifiedToken` to keep your device management service up to date with changes, without having to retrieve all records.

After returning all records for a request, the server includes a `sinceModifiedToken` in the response. Your device management service can pass this `sinceModifiedToken` in subsequent requests to get records modified since generating the token.

> Note:
> Even if the server doesn’t return any records, the response still includes a `sinceModifiedToken` for use in subsequent requests.

## Handle batched responses

Use a `batchToken` to retrieve multiple batches of records when the total number of records exceeds a limit.

To use a `batchToken`, your device management service should:

1. Make an initial request with no `batchToken` (or `sinceModifiedToken`). This request returns all records associated with the provided `sToken`.
2. If the number of records exceeds a server-controlled limit (on the order of several hundred), a `batchToken` value is included in the response, along with the first batch of records. Your device management service should pass this `batchToken` value in a subsequent request to get the next batch of records. As long as additional batches remain, the server returns a new `batchToken` value in its response.
3. After receiving all records for the request, the server includes a `sinceModifiedToken` value in the response. Your device management service can pass this `sinceModifiedToken` in subsequent requests to get records modified since generating the token. If the number of modified records exceeds the limit, the response includes a `batchToken` that you can use to get the next batch of modified records.

> Note:
> Using `sinceModifiedToken` can result in batches with zero records in them. This isn’t an error or an end signal; just move to the next batch.

The following fields are used with batched responses:

|batchToken     |A token used to signify which batch is being returned. The `batchToken` is generated by the server and can be several kilobytes in size.                                                                                                                                                                     |
|---------------|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
|batchCount     |The number of records returned in the current batch.                                                                                                                                                                                                                                                         |
|totalBatchCount|The total number of round trips needed to get the complete result set.                                                                                                                                                                                                                                       |
|overrideIndex  |A value from `1` to the `totalBatchCount` value that specifies the batch of results to return. For requests with a value equal to the `totalBatchCount` value, the `sinceModifiedToken` value is returned.                                                                                                   |
|totalCount     |An estimate of the total number of records that will be returned. This value is only returned for requests that don’t include `batchToken` and the request that started the batch process. The actual number of records returned can be different by the time the client has finished retrieving all records.|

> Tip:
> One of a set of sequential batch requests may return an error. It’s also possible to get a response that includes no token, but also no error number. Because requests should return either a `batchToken` or `sinceModifiedToken`, don’t interpret an error or the lack of a `batchToken` for an individual batch to mean that the last batch has been received. The last batch includes a `sinceModifiedToken`. If an individual batch request fails, the device management service should retry the same batch using the same `batchToken`.

## Perform parallel requests

Both the [`Get Licenses`](/documentation/DeviceManagement/Get-Licenses) and [`Get Users`](/documentation/DeviceManagement/Get-Users-5boi1) endpoints can accept multiple requests in parallel, instead of sequentially, which can significantly reduce the amount of time required to request all licenses and users. You start by making an initial request to receive a `batchToken`. Subsequent requests can be submitted in parallel, by submitting the same `batchToken` and including an `overrideIndex` value from 1 to `totalBatchCount`. The request in which the `overrideIndex` value is equal to the `totalBatchCount` returns the new `sinceModifiedToken`.

For performance reasons, you shouldn’t submit more than five requests simultaneously.

---

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)