Paginating an Imou Device Fleet with listDeviceDetailsByPage

Use listDeviceDetailsByPage with a one-based page, a documented pageSize from 1 to 50, and an administrator or sub-account accessToken. Process every returned device and its channels into an idempotent inventory ledger, advance the page only after the current page is durably stored, and end according to the live response contract. Treat each run as a reconciliation snapshot, because bindings, shares, permissions, and device details can change while paging.

Why it matters

A large fleet cannot be handled safely as one in-memory list. Jobs restart, pages can be replayed, and records may change during a scan. Pagination therefore needs durable progress and idempotent writes, not just a loop. The API is a page-number interface, not a cursor API; any “cursor” in your system should be understood as your own saved job state.

Approach / architecture

Create a scan record with an internal scanId, account scope, token type, selected source, next page, page size, status, and timestamps. Store devices keyed by deviceId, and channels keyed by (deviceId, channelId). Mark each row with the scanId in which it was last observed. Only after a page transaction commits should the worker update nextPage.

For an administrator token, the documented optional source values are bind, share, and bindAndShare, with bindAndShare as the default. The page says this parameter does not work when passed to sub-accounts. Choose and record the scope rather than silently changing it between runs.

Seven implementation steps

1. Create a scan. Fix account, token context, source, and a pageSize between 1 and 50.
2. Request page 1. Send signed HTTPS from the backend with a unique non-empty request id.
3. Validate the result. Persist the platform result and request correlation without storing the token or AppSecret.
4. Upsert devices and channels. Use stable keys and update last-observed metadata in one durable unit.
5. Commit progress. Save the next page only after all records from the current response are committed.
6. Finish using the response contract. Follow current response pagination fields or documented exhaustion behavior; do not guess from a partial network response.
7. Reconcile absence carefully. After a successful complete scan, review rows not observed in that scope. Quarantine before deletion if business impact is high.

APIs / SDKs

listDeviceDetailsByPage is the documented paginated device-detail interface. Required request fields include token, page, and pageSize; page starts at 1, and pageSize is 1–50. The optional relationship source defaults to bindAndShare for the applicable account context.

The development specification defines signed request fields such as appId, time, nonce, sign, and unique non-empty id, as well as region-specific API domains. Keep signing server-side and use the data center assigned to the developer account.

Safe pseudocode:

scan = loadOrCreateScan(accountScope)
while scan.running:
    response = call listDeviceDetailsByPage(
        tokenRef=scan.tokenRef,
        page=scan.nextPage,
        pageSize=scan.pageSize,
        source=scan.source
    )
    transaction:
        upsertDevicesAndChannels(response, scan.id)
        scan.nextPage = deriveNextPageFromDocumentedResponse(response)
        scan.running = hasMoreAccordingToDocumentedResponse(response)

This deliberately avoids pretending to be a runnable Imou SDK method.

Limits & pitfalls

• Do not call the interface a cursor API; it documents numbered pages.
• Do not claim an older list interface is deprecated unless the live documentation says so.
• A sub-account sees its authorized scope, not necessarily the administrator’s full fleet.
• source behavior differs for sub-account calls according to the page.
• Changes during a run can move the logical dataset. Design periodic reconciliation rather than claiming snapshot isolation.
• Do not delete unseen records after an incomplete or failed scan.
• Respect platform quotas and errors shown in the account and live documentation; this article invents no rate or SLA.

Idempotency and restart design

Page processing must be replayable. Use database upsert or an equivalent compare-and-write operation, and make downstream work depend on stable device/channel keys rather than “new row inserted.” If a worker crashes after committing records but before advancing progress, replaying the page should update the same rows and then continue.

Do not put a raw accessToken in the scan row or queue payload. Store a server-side credential reference with appropriate encryption and access controls, then resolve it at call time. Rotate or revoke credentials independently of scan history.

Reconciliation semantics

Define what “missing” means for each scan scope. A device absent from a bind scan could still be visible through sharing; a sub-account scan reflects authorization and can shrink after a policy change. Keep source and account context on every observation. Only a completed scan with the same scope provides evidence for an absence decision.

A conservative production pattern marks a row unseen, confirms the state in a later scan or targeted query, and only then removes it from active views. This is application guidance, not an Imou guarantee. It protects workflows from transient errors and mid-scan changes.

Operations and QA

Expose scan status: current page, records processed, last successful request ID, start time, completion time, and failure category. Alert on stalled progress based on your own operational objective, not an invented platform SLA. Test response replay, crash between commit and checkpoint, token revocation, a changed permission scope, an empty fleet, exactly one full page, and multiple pages.

Review payload storage for sensitive fields. Retain only fields required by the product, restrict support access, and set a retention policy. Device inventory is security-relevant data even when credentials are excluded.

Concurrency choice

Prefer one active page sequence per identical account and source scope unless testing proves a more complex scheduler is safe. Parallel page requests can finish out of order and amplify movement in a changing dataset. If parallelism is required for operational reasons, preserve independent page completion records and do not advance the contiguous checkpoint across a gap. This is a worker-design recommendation; the public API page does not promise a frozen dataset or ordered completion.

Also make cancellation explicit. A cancelled scan is incomplete and cannot justify absence-based cleanup. Keep its observations for diagnostics if policy allows, mark the run non-authoritative, and start a fresh scan with a new scanId.

Document the scan scope beside every checkpoint so a resumed worker cannot accidentally continue under changed account or source parameters.

Start with the live listDeviceDetailsByPage documentation, then validate reconciliation behavior against your own fleet.