Skip to content

Handle an empty page without inventing an end state

Read continuation metadata and errors before interpreting an empty result page.

Guides

Handle an empty page without inventing an end state — what should the operator record?

An empty response page can mean a bounded result has no further rows, an intermediate state or an error represented elsewhere in the response. Inspect the actual receipt before concluding anything. The operational goal is a correct page-chain state, not forcing an empty table into a success or failure label.

Practical operations check
Read continuation metadata and errors before interpreting an empty result page.
Check returned status, continuation and error fields alongside the row array; do not let an empty list erase a visible partial state. Inspect any visible pending or retry condition before setting a terminal state; a zero-length records array alone is insufficient to choose the next action.
Tell the receiver that no rows were accepted from this page, including the actual continuation state, without claiming a source-wide absence of matches. Preserve the chain's prior accepted rows and their scope, since an empty later page does not invalidate evidence already admitted from earlier authorized responses.
01 / Guides

Read the full envelope

Check returned status, continuation and error fields alongside the row array; do not let an empty list erase a visible partial state. Inspect any visible pending or retry condition before setting a terminal state; a zero-length records array alone is insufficient to choose the next action.

02 / Guides

Match documented behavior

Consult the current continuation documentation for the originating tool and avoid inventing a next token when none was returned. If no continuation is returned, do not derive one from a previous token's shape or append a guessed offset to the original request.

03 / Guides

Classify the receipt

Record empty-terminal, empty-pending or empty-error only when actual metadata supports the label; otherwise use unresolved-empty and stop automatic processing. An unresolved-empty receipt should carry a next_action and owner, making it actionable without assigning a falsely definitive complete or no-matches label.

04 / Guides

Bound further attempts

If documented continuation remains available, preserve the original context and honor the returned retry guidance instead of repeatedly requesting immediately. If retry guidance is absent or unclear, stop automatic attempts and route the uncertainty for review rather than selecting an arbitrary aggressive polling cadence.

05 / Guides

Explain the boundary

Tell the receiver that no rows were accepted from this page, including the actual continuation state, without claiming a source-wide absence of matches. Preserve the chain's prior accepted rows and their scope, since an empty later page does not invalidate evidence already admitted from earlier authorized responses.

Keep the boundaries clear.

  • Read continuation metadata and errors before interpreting an empty result page.
  • Operational record: Read the full envelope. Context badges do not certify access.

Start with a read-only check: ask your agent to report actual source coverage before collecting records or exporting an audience.

Primary references

Documentation reviewed 2026-11-15. Product capabilities, client availability and plans can change. Third-party marks identify their products, not an affiliation.

Know what social media shows about you.
Start with a question.

Get started
montage