docs(changelog): add Scores API v3 entry (#3082)

Co-authored-by: Claude Fable 5 <noreply@anthropic.com>

Author: niklassemmler

content/changelog/2026-06-10-scores-v3-api.mdx

@@ -0,0 +1,48 @@
+---
+date: 2026-06-10
+title: "Scores API v3"
+description: Cursor-based pagination, a typed value field, and list-based filters with numeric ranges on the new GET /api/public/v3/scores endpoint.
+author: Niklas
+---
+
+import { ChangelogHeader } from "@/components/changelog/ChangelogHeader";
+
+<ChangelogHeader />
+
+<Callout type="info">
+  The previous `/api/public/v2/scores` endpoints are deprecated. On deployments
+  fully migrated to [Langfuse v4](/docs/v4), they return a 404 error — switch
+  to `/api/public/v3/scores`.
+</Callout>
+
+The new `GET /api/public/v3/scores` endpoint makes querying scores faster and simpler: cursor-based pagination, a single typed `value` field, and filters that accept lists of values and numeric ranges.
+
+```
+GET /api/public/v3/scores?dataType=NUMERIC&name=hallucination,toxicity&valueMax=0.5
+```
+
+Common cases this simplifies:
+
+- **Compare experiment runs** by fetching the scores of one or more dataset runs in a single request, e.g. `experimentId=run-a,run-b`.
+- **Pull only failing evals** by combining `name`, `dataType=NUMERIC`, and `valueMax` in a single request instead of filtering client-side.
+- **Audit annotations per reviewer** with the new `authorUserId` filter, e.g. `source=ANNOTATION&authorUserId=user-123`.
+
+**One typed `value` field.** The v2 split between a numeric `value` and a separate `stringValue` is gone. v3 returns a single `value` whose type follows the `dataType`: a number for `NUMERIC`, a boolean for `BOOLEAN`, and a string for `CATEGORICAL`, `TEXT`, and `CORRECTION`. No more decoding booleans from `1`/`0` or looking up category strings.
+
+**Cursor-based pagination.** Pass `limit` (max 100) and follow the `cursor` from the response `meta` to fetch the next page; it's absent on the final page. This replaces v2's `page` parameter. For recurring full exports to your data warehouse, use the [scheduled blob storage export](/docs/api-and-data-platform/features/export-to-blob-storage) instead of paginating through the API.
+
+**List filters and value ranges.** Most filters now take comma-separated lists — `id`, `name`, `source`, `dataType`, `environment`, `configId`, `queueId`, `authorUserId`, `traceId`, `sessionId`, `observationId`, and `experimentId` (previously `datasetRunId`). Values within one parameter are OR-ed, parameters are AND-ed: `name=hallucination,toxicity&source=EVAL` returns eval scores named either `hallucination` or `toxicity`. The v2 `operator`/`value` pair is replaced by an exact-match `value` list (for `NUMERIC`, `BOOLEAN`, and `CATEGORICAL` scores) plus `valueMin`/`valueMax` range bounds for numeric scores.
+
+**Selective field retrieval.** Responses always include the core fields — `id`, `projectId`, `name`, `value`, `dataType`, `source`, `timestamp`, `environment`, `createdAt`, and `updatedAt` — and stay lean by default; opt into additional field groups via the `fields` parameter:
+
+```
+GET /api/public/v3/scores?fields=details,subject,annotation
+```
+
+- `details` — `comment`, `configId`, `metadata`
+- `subject` — what the score is attached to, as a discriminated object (`kind`: `trace`, `observation`, `session`, or `experiment`) replacing v2's flat `traceId`/`observationId`/`sessionId`/`datasetRunId` fields
+- `annotation` — `authorUserId`, `queueId`
+
+**Migrating from v2.** v3 queries scores directly instead of joining traces, which keeps response times predictable at any volume. Filters therefore target score properties: for trace-level questions like "scores for traces of user X", the [Metrics API](/docs/metrics/features/metrics-api) replaces the v2 `userId` and `traceTags` filters and the `trace` field group. Every filter is now an explicit, typed parameter, replacing v2's JSON-stringified `filter` argument, and fetching a single score works through the `id` filter, replacing the get-by-id endpoint. Invalid filter combinations are rejected with HTTP 400.
+
+The full parameter reference is in the [API docs](https://api.reference.langfuse.com/#tag/scores/GET/api/public/v3/scores).

content/docs/evaluation/evaluation-methods/scores-via-sdk.mdx

@@ -138,7 +138,7 @@ with langfuse.start_as_current_observation(as_type="span", name="my-operation"):
 
 </Tab>
 <Tab>
-Boolean scores must be provided as a float. The value's string equivalent will be automatically populated and is accessible on read. See [API reference](/docs/api) for more details on POST/GET scores endpoints.
+Boolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scores/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.
 
 ```python
 from langfuse import get_client
@@ -295,7 +295,7 @@ await langfuse.flush();
 
 </Tab>
 <Tab>
-Boolean scores must be provided as a float. The value's string equivalent will be automatically populated and is accessible on read. See [API reference](/docs/api) for more details on POST/GET scores endpoints.
+Boolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scores/GET/api/public/v3/scores), the value is returned as a boolean. See [API reference](/docs/api) for more details on POST/GET scores endpoints.
 
 ```ts
 import { LangfuseClient } from "@langfuse/client";
@@ -345,7 +345,7 @@ await langfuse.flush();
 </Tab>
 <Tab>
 
-You can also create scores directly via the [REST API](https://api.reference.langfuse.com/#tag/score/POST/api/public/scores). Authenticate using HTTP Basic Auth with your Langfuse Public Key as username and Secret Key as password.
+You can also create scores directly via the [REST API](https://api.reference.langfuse.com/#tag/legacyscorev1/POST/api/public/scores). Authenticate using HTTP Basic Auth with your Langfuse Public Key as username and Secret Key as password.
 
 <Tabs items={["Numeric", "Categorical", "Boolean", "Text"]}>
 <Tab>
@@ -385,7 +385,7 @@ curl -X POST https://cloud.langfuse.com/api/public/scores \
 
 </Tab>
 <Tab>
-Boolean scores must be provided as a float (`0` or `1`). The value's string equivalent will be automatically populated and is accessible on read.
+Boolean scores must be provided as a float, where `1` is true and `0` is false. When read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scores/GET/api/public/v3/scores), the value is returned as a boolean.
 
 ```bash
 curl -X POST https://cloud.langfuse.com/api/public/scores \
@@ -745,7 +745,7 @@ await langfuse.flush();
 </Tab>
 <Tab>
 
-You can also enforce score configs via the [REST API](https://api.reference.langfuse.com/#tag/score/POST/api/public/scores) by providing a `configId`.
+You can also enforce score configs via the [REST API](https://api.reference.langfuse.com/#tag/legacyscorev1/POST/api/public/scores) by providing a `configId`.
 
 <Tabs items={["Numeric Scores", "Categorical Scores", "Boolean Scores", "Text Scores"]}>
 <Tab>
@@ -842,7 +842,7 @@ Certain score properties might be inferred based on your input:
 
 - **If you don't provide a score data type** it will always be inferred. See tables below for details.
 - **For boolean and categorical scores**, we will provide the score value in both numerical and string format where possible. The score value format that is not provided as input, i.e. the translated value is referred to as the inferred value in the tables below.
-- **On read for boolean scores both** numerical and string representations of the score value will be returned, e.g. both 1 and True.
+- **On read via the [v3 scores API](https://api.reference.langfuse.com/#tag/scores/GET/api/public/v3/scores)**, boolean scores are returned as a single boolean `value`.
 - **For categorical scores**, the string representation is always provided and a numerical mapping of the category will be produced only if a `ScoreConfig` was provided.
 
 Detailed Examples:

content/docs/observability/features/corrections.mdx

@@ -146,7 +146,7 @@ Coming soon: Fetch corrections via the SDK.
 <Tab>
 
 ```bash
-curl -X GET "https://cloud.langfuse.com/api/public/scores?dataType=CORRECTION" \
+curl -X GET "https://cloud.langfuse.com/api/public/v3/scores?dataType=CORRECTION&fields=subject,details" \
   -H "Authorization: Basic <base64_encoded_credentials>"
 ```