[DavidTraina]

What does this PR do?

Brings the docs in line with observations v2 after langfuse/langfuse#19043. Pages can be short or empty while meta.cursor is set, a request can take up to 45 s, a 422 means the server hit a resource limit, and queries without a lower start-time bound only reach back to 2020-01-01.

Langfuse.api docs

• Say to read pages until meta.cursor is absent, pass request_options={"timeout_in_seconds": 60} and from_start_time, and narrow the range on a 422 rather than retrying unchanged. Also note that a JSON startTime filter overrides from_start_time/to_start_time.
• Add a short paging example.
• The flush() note pointed to a "bounded retry pattern" in these docs that didn't exist; it now just says to poll with a deadline.

run_batched_evaluation and batch evaluation docs

• filter: replace "Default: None (fetches all observations)" with the 2020-01-01 floor and a recommendation to add a startTime lower bound.
• max_retries: retries apply only to 408/409/429/5xx responses. Timeouts and 422s stop the run with a resume token.
• has_more_items and the resume token now say more items may exist. With the new time cursors, a full page with a cursor does not guarantee another row.
• Replace the while result.resume_token: example, which looped forever on any persistent fetch failure (422, 400, 401, or a client timeout), with a bounded while result.has_more_items: loop plus a completed=False branch.
• The resume token said the cursor-less fallback fetches observations "strictly before" the timestamp. _build_filter uses <= and skips last_processed_id, and the docs now say so.

Docs only; no behavior change. The generated client docstrings come from the pending regen PR (#2095).

Related PRs

Independent follow-ups to langfuse/langfuse#19043, mergeable in any order: #2097 (batch evaluation stops on empty pages), #2096 (batch evaluation fetch timeout), #2099 (test helpers), #2101 (pagination helper).

Type of change

• Bug fix
• New feature
• Breaking change
• Refactor
• Documentation update
• Tooling, CI, or repo maintenance

Verification

List the main commands you ran:

uv run --frozen ruff check .                                  # All checks passed!
uv run --frozen ruff format --check .                         # 593 files already formatted
uv run --frozen mypy langfuse --no-error-summary              # no issues
uv run --frozen pytest -n auto --dist worksteal tests/unit    # 1003 passed, 2 skipped

I checked that the api docstring example renders as a code block with pdoc. I checked each claim against the server at langfuse/langfuse 728e69371e: events.ts scan bounds and deadline, the withMiddlewares.ts 422 mapping, and the public-api-filter-builder.ts filter precedence. I also checked it against _should_retry in langfuse/api/core/http_client.py.

Checklist

• I self-reviewed the diff using code_review.md.
• I added or updated tests for behavior changes.
• I updated docs, examples, or .env.template if needed.
• I did not hand-edit generated files; if generated files changed, I used the upstream regeneration path.
• I did not commit secrets or credentials.

Confidence Score: 5/5

The PR appears safe to merge.

Summary

Updates observation paging and batch evaluation guidance.

• Observation pages now come with guidance for bounded scans.
• Batch evaluation docs show how to bound runs and handle fetch errors.
• Batch results now describe continuation as possible, not guaranteed.

Acknowledged follow-ups: DavidTraina explicitly identifies empty-page handling as separate PR #2097 and the batch fetch timeout as separate PR #2096.

_{Reviews (1) · Last reviewed commit: "docs: update observations pagination and..." · Reviewed by Greptile}

[claude]

Claude Code Review

This pull request is from a fork — automated review is disabled. A repository maintainer can comment @claude review to run a one-time review.

[CLAassistant]

Thank you for your submission! We really appreciate it. Like many open source projects, we ask that you all sign our Contributor License Agreement before we can accept your contribution.
1 out of 2 committers have signed the CLA.

✅ DavidTraina
❌ hassiebp
_{You have signed the CLA already but the status is still pending? Let us recheck it.}