inventory api paginated wrong mid sweep and agent failed to find hosts

TL;DR

Pagination bugs are silent coverage killers: an off-by-one page index, a page size that changes mid-iteration, or results shifting as hosts register during the sweep can drop a slice of the fleet with no error anywhere. Defend by design: fetch with a stable sort key, record total counts from the API and compare against items received, dedupe by host ID, and run a coverage check (received versus expected count) that fails the sweep loudly if they disagree.

inventory api paginated wrong mid sweep and agent failed to find hosts

Use this when

• Patch coverage reports show fewer hosts than the fleet is known to have.
• The missed hosts cluster (for example one alphabetical or subnet slice).
• The agent log shows it fetched only the first page, or fetched pages with mismatched parameters.

Not for this skill when

• The missing hosts are not in the CMDB or inventory at all. That is a discovery problem upstream of pagination.
• Hosts were fetched but filtered out by wave targeting. That is a targeting decision, recorded separately.

Steps

1. Read the inventory API pagination contract (page or cursor style, total count field, sort stability) from its documentation or responses. Verify: the contract is known, including whether totals are provided
2. Fix the fetch loop to follow the contract exactly (for cursor APIs, use the returned cursor, never synthesize offsets), collecting IDs into a set. Verify: a full fetch of a test collection returns unique IDs equal to the API total
3. Add a coverage assertion: if the API reports a total and your set differs, fail the sweep step with a coverage error rather than proceeding partially. Verify: a deliberately truncated fetch triggers the assertion
4. Log pagination progress (pages fetched, running count) at info level. Verify: a normal sweep log shows the full page sequence
5. Schedule a periodic full-coverage audit comparing sweep membership to the inventory count per segment. Verify: audit results trend at 100 percent coverage

Variant phrasings

inventory api pagination bug missing hosts sweep coverage

The main phrasing.

cursor pagination off by one fleet api agent

The implementation phrasing.

coverage assertion expected vs received host count

The defense phrasing.

Compatibility: Compatibility: Offset, page-number, and cursor paginated REST APIs; the assertion pattern is API-agnostic.

Why it happens

Pagination is a protocol, and agents consume it at machine speed without a human noticing that the result set felt short. Offset pagination over a changing dataset is the worst case: inserts at the front shift every later window, duplicating some hosts and skipping others entirely. Stable sorting and cursor iteration exist precisely to prevent that, but only if the client uses them as specified and verifies the count at the end.

Edge cases / pitfalls

• Where the API offers it, filter by a sweep timestamp or a segment so the working set is frozen during iteration.
• Dedupe protects against overlap but masks under-fetching; the count assertion is the control that matters.
• A sudden coverage drop after an API version change should be treated as a pagination contract change until proven otherwise.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_FfKLgbPWdXYLhcwjCNkLnw