[langfuse-bot]

Generated from langfuse/langfuse main at 1ca8579.

Confidence Score: 5/5

This PR appears safe to merge.

Summary

Updates the generated observations API documentation and adds optional response metadata.

• Observation pages can be empty while a cursor remains.

_{Reviews (1) · Last reviewed commit: "feat(api): update API spec from langfuse..." · Reviewed by Greptile}

[github-actions]

@claude review

[claude]

Claude Code Review

No review was started: this request came from a bot account. Manual reviews can only be requested by someone with write access to this repository. Ask a maintainer to comment @claude review, or have your automation post the comment from a user account with write access.

_{Tip: disable this comment in your organization's Code Review settings.}

[claude]

Nothing blocking. The comments below are optional suggestions. There is no need to push a fix for them before merging.

[claude]

🟣 pre-existing, not blocking: Batch evaluation over observations can stop early and report itself complete with no resume token when the server returns an empty page that still carries a cursor. This change documents that contract but does not update the SDK's own pagination loop. langfuse/batch_evaluation.py:1057 breaks on cursor is None or not items, so an empty page ends the run as finished. Fix: end observation pagination only when meta.cursor is absent, and keep looping on empty pages. Same pattern at 2 sites (langfuse/batch_evaluation.py:1057, tests/support/utils.py:189).
A small fix can ride a push you are already making; otherwise a short reply is enough.

Why this was flagged

The trigger is the API contract this change documents: get_many can return data=[] while meta.cursor is set, with comment filled in (observations_v2meta.py:14-16). One example is a filter whose next matches fall outside the server's scan window. run_batched_evaluation on observations calls _fetch_batch_with_retry (batch_evaluation.py:1114-1123) and then runs if cursor is None or not items: has_more = False; break at batch_evaluation.py:1057. The result therefore has completed=True, has_more_items=False and resume_token=None (lines 1080-1085), even though more matching observations exist. They are never scored, and the caller gets no token to resume from. The e2e helper get_observations in tests/support/utils.py:189 stops the same way on not response.data, so it can return a partial list. The base client did not document this, but the loop ignores the cursor whenever a page is empty.

Verification: pre-existing. Trigger: the v2 observations endpoint returns data=[] while meta.cursor is still set. The loop then runs cursor = next_cursor; if cursor is None or not items: has_more = False; break (batch_evaluation.py:1056-1059). An empty page that still has a cursor therefore ends the run. The base commit has the same loop at 1056-1059.