SEIBRO dividend API pagination: reconcile count and collected rows

Symptoms

A count response and a fully traversed dividend list can disagree. The reviewed SEIBRO stock adapter treats this as an incomplete observation rather than inventing missing events. LIST_CNT describes the count receipt; START_PAGE and END_PAGE describe inclusive request ranges. These names come from the reviewed integration, not a newly verified public REST specification. The historical application lock pins httpx==0.28.1.

Cause

A collection can stop too early, repeat an overlapping page, accept a short page, or observe a changing dataset between the initial count and final request. The available evidence does not establish which upstream mechanism explains every historical discrepancy. The adapter checks each page’s expected row count, raw-row duplication, a terminal range beyond the pinned total, and a second count. Its application error stock_page_coverage_mismatch is not a SEIBRO HTTP error code.

Safe resolution

This reduced collector models those coverage checks with injected count/page functions. The default 500-row page size follows the reviewed adapter, not a newly asserted service quota. Row dictionaries are assumed to contain scalar fields already validated by a transport/parser boundary.

def collect_complete(count, fetch_page, *, page_size=500):
    if type(page_size) is not int or page_size <= 0:
        raise ValueError("Invalid page size")
    total = count()
    if type(total) is not int or total < 0:
        raise ValueError("Invalid count")
    rows, seen = [], set()
    for offset in range(0, total + page_size, page_size):
        page = fetch_page(offset + 1, offset + page_size)
        expected = min(page_size, max(0, total - offset))
        if not isinstance(page, list) or len(page) != expected:
            raise ValueError("stock_page_coverage_mismatch")
        for row in page:
            fingerprint = tuple(sorted(row.items()))
            if fingerprint in seen:
                raise ValueError("stock_repeated_or_overlapping_page")
            seen.add(fingerprint)
        rows.extend(page)
    if len(rows) != total or count() != total:
        raise ValueError("stock_total_count_drift")
    return rows

Verification

Synthetic Python examples were checked on 2026-10-16; the original application tests and live provider APIs were not run.

Use 501 distinct synthetic rows and assert requests for 1–500, 501–1000 and the empty 1001–1500 range, plus two count calls. Negative fixtures shorten the first page, overlap the second page, return a nonempty terminal page, or change the second count. Each must raise before any financial confirmation or persistence step. Keep the original window available for investigation rather than silently treating partial rows as complete.

The checked-in tests extract this published Python block and exercise the same synthetic boundary cases. Re-run with npm test.

Limitations

Equal counts do not establish that every row is the right financial fact or that the source snapshot was immutable. A production adapter still needs bounded pages/bytes/time, issuer and share-class identity, confirmed cash-dividend status, amount and payment-date cross-checks. SHOTN_ISIN is a short security code in the reviewed integration, not a full ISIN. This is not a claim that the historical source discrepancy was repaired or that splitting windows has already recovered it. The SEIBRO profile documents the research status; the pagination guide covers general traversal patterns.

Implementation evidence was reviewed at pinned GetBeta revision 890c2531b76c. Source-repository links may require access; the public code above is a reduced adaptation without credentials or customer data. Search expressions are candidates, with no search-volume, indexing or ranking claim.

Editorial update (2026-10-20): the strict count rule above illustrates the pinned historical adapter. The later EODHD and SEIBRO source-selection case describes the reviewed stock adapter’s bounded exception for a stable overstated count with a verified empty tail. That exception does not certify complete history.