Vercel Blob list(): choosing a page limit and cursor policy for a full-store scan

Direct answer

Limit: Set limit explicitly in code. Do not rely on a default or a maximum. Confirm the effective default and the server-enforced maximum for your exact SDK version and Blob plan by running a minimal list() call in the target runtime and logging the returned page size when limit is omitted, and by testing an explicit high limit to observe truncation or error. Cursor lifetime: Treat a continuation cursor as ephemeral and short-lived. It is designed for sequential paging within one logical scan, not for durable persistence across hours or days. If a scan must pause between serverless invocations, persist the cursor and resume promptly. Have a fallback to restart the scan from the beginning if the cursor is rejected. Consistency: Point-in-time-consistent enumeration is not documented as guaranteed. Mutations during enumeration can lead to skips or duplicates because ordering is not guaranteed stable across requests. The reliable pattern is idempotent processing with post-scan reconciliation by blob key, e.g., tracking seen keys and re-checking modified timestamps.

Confirmed facts

• list() returns a bounded page of blob metadata plus an opaque continuation cursor and a hasMore flag. Callers pass the cursor back to continue.
• limit is an explicit parameter that controls page size and therefore round trips and function duration.
• folded vs expanded modes change page contents. Folded views return prefix aggregates, which alters counting and completeness assumptions for a full store scan.

Likely but version-sensitive

The following is based on current model knowledge and requires current verification in your environment:

• Default and maximum limit depend on SDK version and Blob plan and are not stable across releases. Set limit explicitly and verify.
• Continuation cursors are intended for short-lived sequential paging. Resuming after a deliberate delay may be rejected. Design checkpointed pagination with cursor persisted between invocations and a restart strategy.
• Pagination is not documented as point-in-time consistent. The expected reliable approach is key-based reconciliation after the pass.

Steps for this case

1. Pin limit explicitly, e.g., choose a value that keeps one page well under your function duration cap and network budget. Verify effective default and max for your SDK version and plan.
2. Use expanded mode for a full store scan unless prefix aggregation is required. Folded mode changes what a page contains.
3. Persist cursor and hasMore between invocations. Resume promptly; on cursor error, restart from the beginning with a fresh enumeration.
4. Process idempotently by blob key. After the pass, reconcile the key set against a source of truth or re-check modified timestamps to catch skips/duplicates from concurrent writes.

Missing diagnostic detail that changes the recommendation: the exact SDK version and Blob plan you are running. The default and maximum limit, and cursor tolerance, are version and plan dependent and must be confirmed in your environment before finalizing the page size.