backup catalog API timed out when agent tried listing snapshots and the sweep failed

TL;DR

Listing every snapshot in a big catalog in one call is the timeout recipe: the server builds a huge response while the agent waits. Page the listing with modest page sizes, push filters like job name and date range to the server, and cache the snapshot inventory for the sweep duration so twenty checks do not re-list the same catalog twenty times.

backup catalog API timed out when agent tried listing snapshots and the sweep failed

Use this when

• Agent snapshot listing times out on large catalogs but works on small test systems.
• The API call eventually returns if the timeout is massively raised, with a huge payload.
• Other agents listing the same catalog hit the same wall.

Not for this skill when

• The catalog service is down entirely. Availability problem.
• The catalog database is corrupt and rebuilds fail. Deeper data problem.

Steps

1. Reproduce the listing call with timing and response size logging. Verify: the unfiltered call cost is measured
2. Add pagination with a page size the API answers quickly, iterating until the inventory is complete. Verify: paged listing completes within timeouts
3. Apply server-side filters for the sweep scope, such as one job or a date window, instead of filtering client-side. Verify: transferred records drop sharply
4. Cache the resulting inventory in the agent run state with a timestamp and reuse it across checks in the same sweep. Verify: the sweep issues one listing sequence, not one per check
5. Run the full sweep against the large catalog. Verify: listing succeeds and checks proceed without catalog timeouts

Variant phrasings

catalog api pagination timeout large inventory

The pagination phrasing.

agent list snapshots slow api filter

The filter variant.

backup api list timeout page size

The page-size wording.

Compatibility: Agents calling Veeam, Commvault and cloud backup catalog REST APIs with list endpoints supporting pagination and filtering.

Why it happens

Catalog list endpoints are usually built for consoles showing one page, not agents asking for everything. An unfiltered list forces the server to serialise the entire inventory and the agent to hold it, so both sides time out as catalogs grow. Pagination, server-side filtering and sweep-level caching align the agent with how the API was designed to be used.

Edge cases / pitfalls

• Respect the API maximum page size. Asking for a giant page is an unfiltered list in disguise.
• If the API offers a count or summary endpoint, use it to size the sweep before listing details.
• Stale cached inventories cause checks against deleted snapshots. Bind cache lifetime to the single sweep.

Provenance

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