🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.
TypeScript analyticsautogenevaluationlangchainlarge-language-modelsllama-indexllmllm-evaluationllm-observabilityllmopsmonitoringobservabilityopen-sourceopenaiplaygroundprompt-engineeringprompt-managementself-hostedycombinator
feat(v4-modal): copy improvements (#16700)
Hassieb Pakzad5d0d4fa85231
diff --git a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.tsindex bb452f5bcb..ad7bf12d13 100644--- a/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts+++ b/web/src/__tests__/server/unit/v4TransitionRouter.servertest.ts@@ -2297,6 +2297,105 @@ describe("v4TransitionRouter", () => {});});+ it.each(["Claude Code/1.0", "codex-cli/1.2.3", "curl/8.7.1"])(+ "does not require an API action for deprecated calls made only by %s",+ async (userAgent) => {+ await seedRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([]),+ [experimentPostUsageCacheKey]: experimentPostBlob(false),+ [legacyApiUsageCacheKey]: legacyApiBlob([+ {+ entrypoint: "publicapi: GET /api/public/traces",+ count: 2,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ callers: [+ {+ userAgent,+ count: 2,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ },+ ],+ },+ ]),+ });+ mockedQueryClickhouse.mockResolvedValue([]);+ const caller = createCaller(mockPrismaForActions());++ await expect(+ caller.migrationActions({ projectId }),+ ).resolves.toMatchObject({+ sdkActionNeeded: false,+ experimentsActionNeeded: false,+ apisActionNeeded: false,+ evalsActionNeeded: false,+ exportsActionNeeded: false,+ });+ },+ );++ it("keeps the API action when any caller is not an agent or curl", async () => {+ await seedRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([]),+ [experimentPostUsageCacheKey]: experimentPostBlob(false),+ [legacyApiUsageCacheKey]: legacyApiBlob([+ {+ entrypoint: "publicapi: GET /api/public/traces",+ count: 3,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ callers: [+ {+ userAgent: "codex-cli/1.2.3",+ count: 2,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ },+ {+ userAgent: "langfuse-python/3.9.0",+ count: 1,+ lastSeen: "2026-06-24T11:00:00.000000Z",+ },+ ],+ },+ ]),+ });+ mockedQueryClickhouse.mockResolvedValue([]);+ const caller = createCaller(mockPrismaForActions());++ await expect(+ caller.migrationActions({ projectId }),+ ).resolves.toMatchObject({+ apisActionNeeded: true,+ });+ });++ it("keeps the API action for an aggregated unknown caller", async () => {+ await seedRedisCache({+ [sdkUsageCacheKey]: sdkUsageBlob([]),+ [experimentPostUsageCacheKey]: experimentPostBlob(false),+ [legacyApiUsageCacheKey]: legacyApiBlob([+ {+ entrypoint: "publicapi: GET /api/public/traces",+ count: 2,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ callers: [+ {+ isOther: true,+ count: 2,+ lastSeen: "2026-06-24T12:00:00.000000Z",+ },+ ],+ },+ ]),+ });+ mockedQueryClickhouse.mockResolvedValue([]);+ const caller = createCaller(mockPrismaForActions());++ await expect(+ caller.migrationActions({ projectId }),+ ).resolves.toMatchObject({+ apisActionNeeded: true,+ });+ });+it("short-circuits partner-managed (forced v3) projects without any I/O", async () => {await seedRedisCache();sharedServerMock.isForceV3ExperienceProject.mockReturnValueOnce(true);diff --git a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsxindex 0394de6cd8..e010c73c50 100644--- a/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.clienttest.tsx@@ -338,12 +338,15 @@ describe("V4MigrationDetailsContent", () => {expect(screen.queryByText("Legacy APIs")).not.toBeInTheDocument();expect(screen.queryByText("Legacy Integrations")).not.toBeInTheDocument();- expect(- screen.getByRole("link", { name: "GET /api/public/traces" }),- ).toHaveAttribute(+ const endpointLink = screen.getByRole("link", {+ name: "GET /api/public/traces",+ });+ expect(endpointLink).toHaveAttribute("href","https://langfuse.com/faq/all/deprecated-api-migration",);+ expect(endpointLink).not.toHaveClass("font-bold");+ expect(within(endpointLink).getByText("traces")).toHaveClass("font-bold");expect(screen.getByTitle("Last seen at 2026-07-23T10:37:00Z"),).toHaveTextContent(/42 calls · last seen/);@@ -429,9 +432,9 @@ describe("V4MigrationDetailsContent", () => {render(<V4MigrationDetailsContent projectId="project-1" />);expect(screen.getByText("Langfuse Python SDK 3.9.0")).toBeInTheDocument();- expect(screen.getByText("client.api.trace.get(...)")).toBeInTheDocument();+ expect(screen.getByText("client.api.trace.get")).toBeInTheDocument();expect(- screen.getByText("client.api.observations.get_many(trace_id=trace_id)"),+ screen.getByText("client.api.observations.get_many"),).toBeInTheDocument();expect(screen.getByText("4.0.0 or newer")).toBeInTheDocument();expect(screen.getByText("Codex")).toBeInTheDocument();@@ -466,6 +469,31 @@ describe("V4MigrationDetailsContent", () => {);});+ it("shows route totals without a caller section for unknown-only callers", () => {+ mocks.migrationData.apiUsage = [+ {+ endpoint: "GET /api/public/traces",+ count: 42,+ lastSeen: "2026-07-23T10:37:00Z",+ callers: [+ {+ isOther: true,+ count: 42,+ lastSeen: "2026-07-23T10:37:00Z",+ },+ ],+ },+ ];++ render(<V4MigrationDetailsContent projectId="project-1" />);++ expect(+ screen.getByTitle("Last seen at 2026-07-23T10:37:00Z"),+ ).toHaveTextContent(/42 calls · last seen/);+ expect(screen.queryByText("Unknown callers")).not.toBeInTheDocument();+ expect(screen.queryByRole("list")).not.toBeInTheDocument();+ });+it("collapses clean sections into one up-to-date summary", () => {mocks.migrationData.apis = { status: "loaded", count: 0 };mocks.migrationData.exports = { status: "loaded", count: 0 };diff --git a/web/src/features/v4-migration/V4MigrationContent.tsx b/web/src/features/v4-migration/V4MigrationContent.tsxindex e15a9aa9e9..1201e51756 100644--- a/web/src/features/v4-migration/V4MigrationContent.tsx+++ b/web/src/features/v4-migration/V4MigrationContent.tsx@@ -207,12 +207,14 @@ function ExternalLink({children,className,analytics,+ ariaLabel,}: {href: string;children: ReactNode;className?: string;/** Which guidance link in which section — for section_link_clicked. */analytics?: { section: string; link: string };+ ariaLabel?: string;}) {const capture = usePostHogClientCapture();return (@@ -221,6 +223,7 @@ function ExternalLink({target="_blank"rel="noopener noreferrer"className={cn("underline", className)}+ aria-label={ariaLabel}onClick={analytics? () => capture("v4_migration:section_link_clicked", analytics)@@ -913,36 +916,46 @@ export function V4MigrationApisSection({) : usage.length > 0 ? (<><p className="text-muted-foreground mb-2 text-sm">- You've called these deprecated endpoints in the last{" "}- {V4_MIGRATION_LOOKBACK_DAYS} days. Counts refresh about every 15- minutes and can lag live traffic. They stop working soon; the{" "}+ You've recently called deprecated endpoints that will stop+ working after the migration deadline. Please check the{" "}<ExternalLinkhref={DEPRECATED_API_MIGRATION_URL}analytics={{ section: "apis", link: "deprecated_api_docs" }}>migration guide- </ExternalLink>{" "}- maps each endpoint to its replacement.+ </ExternalLink></p><div className="flex flex-col gap-3">{usage.map((row) => {const roundedCount = Math.max(1, Math.round(row.count));const callers = row.callers ?? [];+ const hasKnownCallers = callers.some((caller) => !caller.isOther);+ const publicApiPrefix = "/api/public/";+ const publicApiPrefixStart =+ row.endpoint.indexOf(publicApiPrefix);+ const publicApiPrefixEnd =+ publicApiPrefixStart < 0+ ? 0+ : publicApiPrefixStart + publicApiPrefix.length;return (<div key={row.endpoint} className="rounded-md border p-3"><div className="flex flex-wrap items-baseline justify-between gap-x-2"><ExternalLinkhref={DEPRECATED_API_MIGRATION_URL}- className="text-sm font-bold"+ className="text-sm"analytics={{section: "apis",link: "deprecated_api_docs",}}+ ariaLabel={row.endpoint}>- {row.endpoint}+ {row.endpoint.slice(0, publicApiPrefixEnd)}+ <span className="font-bold">+ {row.endpoint.slice(publicApiPrefixEnd)}+ </span></ExternalLink>- {callers.length === 0 ? (+ {!hasKnownCallers ? (<spanclassName="text-muted-foreground text-sm whitespace-nowrap"title={`Last seen at ${row.lastSeen}`}@@ -953,7 +966,7 @@ export function V4MigrationApisSection({</span>) : null}</div>- {callers.length > 0 ? (+ {hasKnownCallers ? (<ul className="mt-2 flex flex-col gap-2">{callers.map((caller, index) => {const codingAgent = getCodingAgentName(diff --git a/web/src/features/v4-migration/apiMigrationGuidance.clienttest.ts b/web/src/features/v4-migration/apiMigrationGuidance.clienttest.tsindex 6a7875b794..c27b80067c 100644--- a/web/src/features/v4-migration/apiMigrationGuidance.clienttest.ts+++ b/web/src/features/v4-migration/apiMigrationGuidance.clienttest.ts@@ -5,12 +5,12 @@ import {} from "./apiMigrationGuidance";describe("getApiMigrationGuidance", () => {- it("provides exact Python trace migration methods", () => {+ it("provides bare Python trace migration methods", () => {expect(getApiMigrationGuidance("GET /api/public/traces/{id}", "python", "3.9.0"),).toEqual({- currentMethod: "client.api.trace.get(...)",- replacementMethod: "client.api.observations.get_many(trace_id=trace_id)",+ currentMethod: "client.api.trace.get",+ replacementMethod: "client.api.observations.get_many",replacement: "GET /api/public/v2/observations",minimumVersion: "4.0.0",requiresUpgrade: true,@@ -25,24 +25,24 @@ describe("getApiMigrationGuidance", () => {"5.4.0",),).toMatchObject({- currentMethod: "client.api.scores.getMany(...)",- replacementMethod: "client.api.scoresV3.getManyV3(...)",+ currentMethod: "client.api.scores.getMany",+ replacementMethod: "client.api.scoresV3.getManyV3",minimumVersion: "5.5.0",requiresUpgrade: true,});});- it("preserves the score ID when migrating the legacy score endpoint", () => {+ it("uses bare score methods for the legacy score endpoint", () => {expect(getApiMigrationGuidance("GET /api/public/scores/{id}", "python", "4.8.1"),).toMatchObject({- currentMethod: "client.api.scores.get_by_id(...)",- replacementMethod: "client.api.scores_v3.get_many_v3(id=score_id)",- replacement: "GET /api/public/v3/scores?id=<score id>",+ currentMethod: "client.api.scores.get_by_id",+ replacementMethod: "client.api.scores_v3.get_many_v3",+ replacement: "GET /api/public/v3/scores",});});- it("preserves the score ID when migrating the v2 score endpoint", () => {+ it("uses the bare v3 route when migrating the v2 score endpoint", () => {expect(getApiMigrationGuidance("GET /api/public/v2/scores/{id}",@@ -50,11 +50,11 @@ describe("getApiMigrationGuidance", () => {undefined,),).toEqual({- replacement: "GET /api/public/v3/scores?id=<score id>",+ replacement: "GET /api/public/v3/scores",});});- it("bounds the observation ID lookup by time", () => {+ it("uses bare observation guidance for the legacy ID lookup", () => {expect(getApiMigrationGuidance("GET /api/public/observations/{id}",@@ -62,10 +62,8 @@ describe("getApiMigrationGuidance", () => {"5.5.0",),).toMatchObject({- replacementMethod:- 'client.api.observations.getMany({ filter: "<id filter>", fromStartTime, toStartTime })',- replacement:- "GET /api/public/v2/observations?filter=<id filter>&fromStartTime=<from>&toStartTime=<to>",+ replacementMethod: "client.api.observations.getMany",+ replacement: "GET /api/public/v2/observations",});});@@ -82,20 +80,16 @@ describe("getApiMigrationGuidance", () => {});});- it("warns that trace metrics have no drop-in v2 replacement", () => {+ it("uses bare metrics guidance", () => {expect(getApiMigrationGuidance("GET /api/public/metrics", "python", "4.8.1"),).toMatchObject({- replacementMethod: expect.stringContaining(- "traces view has no drop-in v2 replacement",- ),- replacement: expect.stringContaining(- "traces view has no drop-in v2 replacement",- ),+ replacementMethod: "client.api.metrics.metrics",+ replacement: "GET /api/public/v2/metrics",});});- it("uses a bounded observation scan when migrating session listing", () => {+ it("uses bare observation guidance when migrating session listing", () => {expect(getApiMigrationGuidance("GET /api/public/sessions",@@ -103,15 +97,13 @@ describe("getApiMigrationGuidance", () => {"5.5.0",),).toMatchObject({- currentMethod: "client.api.sessions.list(...)",- replacementMethod:- "client.api.observations.getMany({ fromStartTime, toStartTime }) // group by sessionId",- replacement:- "GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>, then group rows by sessionId",+ currentMethod: "client.api.sessions.list",+ replacementMethod: "client.api.observations.getMany",+ replacement: "GET /api/public/v2/observations",});});- it("preserves the session ID and time bounds when migrating session lookup", () => {+ it("uses bare observation guidance when migrating a session lookup", () => {expect(getApiMigrationGuidance("GET /api/public/sessions/{id}",@@ -119,11 +111,9 @@ describe("getApiMigrationGuidance", () => {"4.8.1",),).toMatchObject({- currentMethod: "client.api.sessions.get(...)",- replacementMethod:- 'client.api.observations.get_many(filter="<sessionId filter>", from_start_time=..., to_start_time=...)',- replacement:- "GET /api/public/v2/observations?filter=<sessionId filter>&fromStartTime=<from>&toStartTime=<to>",+ currentMethod: "client.api.sessions.get",+ replacementMethod: "client.api.observations.get_many",+ replacement: "GET /api/public/v2/observations",});});@@ -158,19 +148,15 @@ describe("getApiMigrationGuidance", () => {it.each(["GET /api/public/dataset-run-items","GET /api/public/datasets/{datasetName}/runs/{runName}",- ])(- "preserves dataset and renamed experiment filters for %s",- (entrypoint) => {- expect(- getApiMigrationGuidance(entrypoint, "javascript", "5.5.0"),- ).toMatchObject({- replacementMethod:- "client.api.experiments.listItems({ datasetId, experimentName: runName, fromStartTime })",- });- },- );+ ])("uses the bare experiment-items method for %s", (entrypoint) => {+ expect(+ getApiMigrationGuidance(entrypoint, "javascript", "5.5.0"),+ ).toMatchObject({+ replacementMethod: "client.api.experiments.listItems",+ });+ });- it("preserves the dataset filter when listing experiments", () => {+ it("uses the bare experiments method when listing experiments", () => {expect(getApiMigrationGuidance("GET /api/public/datasets/{datasetName}/runs",@@ -178,8 +164,7 @@ describe("getApiMigrationGuidance", () => {"4.8.1",),).toMatchObject({- replacementMethod:- "client.api.experiments.list(dataset_id=dataset_id, from_start_time=from_start_time)",+ replacementMethod: "client.api.experiments.list",});});});diff --git a/web/src/features/v4-migration/apiMigrationGuidance.ts b/web/src/features/v4-migration/apiMigrationGuidance.tsindex 127b342d84..fc1e509e2a 100644--- a/web/src/features/v4-migration/apiMigrationGuidance.ts+++ b/web/src/features/v4-migration/apiMigrationGuidance.ts@@ -23,15 +23,13 @@ const guidanceByEndpoint: Record<replacement: "GET /api/public/v2/observations",methods: observationsMethods({python: {- current: "client.api.trace.list(...)",- replacement:- "client.api.observations.get_many(from_start_time=..., to_start_time=...)",+ current: "client.api.trace.list",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.trace.list(...)",- replacement:- "client.api.observations.getMany({ fromStartTime, toStartTime })",+ current: "client.api.trace.list",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},}),@@ -40,13 +38,13 @@ const guidanceByEndpoint: Record<replacement: "GET /api/public/v2/observations",methods: observationsMethods({python: {- current: "client.api.trace.get(...)",- replacement: "client.api.observations.get_many(trace_id=trace_id)",+ current: "client.api.trace.get",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.trace.get(...)",- replacement: "client.api.observations.getMany({ traceId })",+ current: "client.api.trace.get",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},}),@@ -55,33 +53,28 @@ const guidanceByEndpoint: Record<replacement: "GET /api/public/v2/observations",methods: {python: {- current: "client.api.legacy.observations_v1.get_many(...)",- replacement:- "client.api.observations.get_many(from_start_time=..., to_start_time=...)",+ current: "client.api.legacy.observations_v1.get_many",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.legacy.observationsV1.getMany(...)",- replacement:- "client.api.observations.getMany({ fromStartTime, toStartTime })",+ current: "client.api.legacy.observationsV1.getMany",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},},},"GET /api/public/observations/{id}": {- replacement:- "GET /api/public/v2/observations?filter=<id filter>&fromStartTime=<from>&toStartTime=<to>",+ replacement: "GET /api/public/v2/observations",methods: {python: {- current: "client.api.legacy.observations_v1.get(...)",- replacement:- 'client.api.observations.get_many(filter="<id filter>", from_start_time=..., to_start_time=...)',+ current: "client.api.legacy.observations_v1.get",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.legacy.observationsV1.get(...)",- replacement:- 'client.api.observations.getMany({ filter: "<id filter>", fromStartTime, toStartTime })',+ current: "client.api.legacy.observationsV1.get",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},},@@ -90,144 +83,126 @@ const guidanceByEndpoint: Record<replacement: "GET /api/public/v3/scores",methods: {python: {- current: "client.api.scores.get_many(...)",- replacement: "client.api.scores_v3.get_many_v3(...)",+ current: "client.api.scores.get_many",+ replacement: "client.api.scores_v3.get_many_v3",minimumVersion: "4.8.1",},javascript: {- current: "client.api.scores.getMany(...)",- replacement: "client.api.scoresV3.getManyV3(...)",+ current: "client.api.scores.getMany",+ replacement: "client.api.scoresV3.getManyV3",minimumVersion: "5.5.0",},},},"GET /api/public/v2/scores/{id}": {- replacement: "GET /api/public/v3/scores?id=<score id>",+ replacement: "GET /api/public/v3/scores",methods: {python: {- current: "client.api.scores.get_by_id(...)",- replacement: "client.api.scores_v3.get_many_v3(id=score_id)",+ current: "client.api.scores.get_by_id",+ replacement: "client.api.scores_v3.get_many_v3",minimumVersion: "4.8.1",},javascript: {- current: "client.api.scores.getById(...)",- replacement: "client.api.scoresV3.getManyV3({ id: scoreId })",+ current: "client.api.scores.getById",+ replacement: "client.api.scoresV3.getManyV3",minimumVersion: "5.5.0",},},},"GET /api/public/scores/{id}": {- replacement: "GET /api/public/v3/scores?id=<score id>",+ replacement: "GET /api/public/v3/scores",methods: {python: {- current: "client.api.scores.get_by_id(...)",- replacement: "client.api.scores_v3.get_many_v3(id=score_id)",+ current: "client.api.scores.get_by_id",+ replacement: "client.api.scores_v3.get_many_v3",minimumVersion: "4.8.1",},javascript: {- current: "client.api.scores.getById(...)",- replacement: "client.api.scoresV3.getManyV3({ id: scoreId })",+ current: "client.api.scores.getById",+ replacement: "client.api.scoresV3.getManyV3",minimumVersion: "5.5.0",},},},"GET /api/public/sessions": {- replacement:- "GET /api/public/v2/observations?fromStartTime=<from>&toStartTime=<to>, then group rows by sessionId",+ replacement: "GET /api/public/v2/observations",methods: observationsMethods({python: {- current: "client.api.sessions.list(...)",- replacement:- "client.api.observations.get_many(from_start_time=..., to_start_time=...) # group by session_id",+ current: "client.api.sessions.list",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.sessions.list(...)",- replacement:- "client.api.observations.getMany({ fromStartTime, toStartTime }) // group by sessionId",+ current: "client.api.sessions.list",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},}),},"GET /api/public/sessions/{id}": {- replacement:- "GET /api/public/v2/observations?filter=<sessionId filter>&fromStartTime=<from>&toStartTime=<to>",+ replacement: "GET /api/public/v2/observations",methods: {python: {- current: "client.api.sessions.get(...)",- replacement:- 'client.api.observations.get_many(filter="<sessionId filter>", from_start_time=..., to_start_time=...)',+ current: "client.api.sessions.get",+ replacement: "client.api.observations.get_many",minimumVersion: "4.0.0",},javascript: {- current: "client.api.sessions.get(...)",- replacement:- 'client.api.observations.getMany({ filter: "<sessionId filter>", fromStartTime, toStartTime })',+ current: "client.api.sessions.get",+ replacement: "client.api.observations.getMany",minimumVersion: "4.0.0",},},},"GET /api/public/metrics": {- replacement:- "GET /api/public/v2/metrics with a supported observations or scores query; the traces view has no drop-in v2 replacement",+ replacement: "GET /api/public/v2/metrics",methods: {python: {- current: "client.api.legacy.metrics_v1.metrics(...)",- replacement:- "client.api.metrics.metrics(...) with an observations or scores view; the traces view has no drop-in v2 replacement",+ current: "client.api.legacy.metrics_v1.metrics",+ replacement: "client.api.metrics.metrics",},javascript: {- current: "client.api.legacy.metricsV1.metrics(...)",- replacement:- "client.api.metrics.metrics(...) with an observations or scores view; the traces view has no drop-in v2 replacement",+ current: "client.api.legacy.metricsV1.metrics",+ replacement: "client.api.metrics.metrics",},},},"GET /api/public/dataset-run-items": {- replacement:- "GET /api/public/experiment-items?datasetId=<dataset id>&experimentName=<run name>&fromStartTime=<ISO timestamp>",+ replacement: "GET /api/public/experiment-items",methods: {python: {- current: "client.api.dataset_run_items.list(...)",- replacement:- "client.api.experiments.list_items(dataset_id=dataset_id, experiment_name=run_name, from_start_time=from_start_time)",+ current: "client.api.dataset_run_items.list",+ replacement: "client.api.experiments.list_items",},javascript: {- current: "client.api.datasetRunItems.list(...)",- replacement:- "client.api.experiments.listItems({ datasetId, experimentName: runName, fromStartTime })",+ current: "client.api.datasetRunItems.list",+ replacement: "client.api.experiments.listItems",},},},"GET /api/public/datasets/{datasetName}/runs": {- replacement:- "GET /api/public/experiments?datasetId=<dataset id>&fromStartTime=<ISO timestamp>",+ replacement: "GET /api/public/experiments",methods: {python: {- current: "client.api.datasets.get_runs(...)",- replacement:- "client.api.experiments.list(dataset_id=dataset_id, from_start_time=from_start_time)",+ current: "client.api.datasets.get_runs",+ replacement: "client.api.experiments.list",},javascript: {- current: "client.api.datasets.getRuns(...)",- replacement:- "client.api.experiments.list({ datasetId, fromStartTime })",+ current: "client.api.datasets.getRuns",+ replacement: "client.api.experiments.list",},},},"GET /api/public/datasets/{datasetName}/runs/{runName}": {- replacement:- "GET /api/public/experiment-items?datasetId=<dataset id>&experimentName=<run name>&fromStartTime=<ISO timestamp>",+ replacement: "GET /api/public/experiment-items",methods: {python: {- current: "client.api.datasets.get_run(...)",- replacement:- "client.api.experiments.list_items(dataset_id=dataset_id, experiment_name=run_name, from_start_time=from_start_time)",+ current: "client.api.datasets.get_run",+ replacement: "client.api.experiments.list_items",},javascript: {- current: "client.api.datasets.getRun(...)",- replacement:- "client.api.experiments.listItems({ datasetId, experimentName: runName, fromStartTime })",+ current: "client.api.datasets.getRun",+ replacement: "client.api.experiments.listItems",},},},diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.tsindex 49212e0742..0e7c2fa219 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.clienttest.ts@@ -3,6 +3,7 @@ import { vi } from "vitest";import {useAccountV4MigrationData,+ useProjectV4MigrationData,useProjectV4MigrationActions,} from "@/src/features/v4-migration/hooks/useV4MigrationData";@@ -11,6 +12,10 @@ const mocks = vi.hoisted(() => ({traceLevelEvalSummaryByProject: vi.fn(),legacyApiUsageSummaryByProject: vi.fn(),sdkUsageSummaryByProject: vi.fn(),+ summaryUseQuery: vi.fn(),+ traceLevelEvalSummaryUseQuery: vi.fn(),+ legacyApiUsageSummaryUseQuery: vi.fn(),+ sdkUsageSummaryUseQuery: vi.fn(),migrationActionsUseQuery: vi.fn(),queryResultSets: [] as unknown[][],}));@@ -38,6 +43,21 @@ vi.mock("@/src/utils/api", () => ({return mocks.queryResultSets.shift() ?? [];},v4Transition: {+ summary: {+ useQuery: (...args: unknown[]) => mocks.summaryUseQuery(...args),+ },+ traceLevelEvalSummary: {+ useQuery: (...args: unknown[]) =>+ mocks.traceLevelEvalSummaryUseQuery(...args),+ },+ legacyApiUsageSummary: {+ useQuery: (...args: unknown[]) =>+ mocks.legacyApiUsageSummaryUseQuery(...args),+ },+ sdkUsageSummary: {+ useQuery: (...args: unknown[]) =>+ mocks.sdkUsageSummaryUseQuery(...args),+ },migrationActions: {useQuery: (...args: unknown[]) =>mocks.migrationActionsUseQuery(...args),@@ -46,6 +66,10 @@ vi.mock("@/src/utils/api", () => ({},}));+vi.mock("@/src/features/v4-migration/useForceV3Experience", () => ({+ useForceV3Experience: () => false,+}));+const loadedQuery = <T>(data: T) => ({data,isError: false,@@ -201,6 +225,97 @@ describe("account v4 migration data", () => {forceV3Experience: true,});});++ it("excludes agent-only deprecated API usage from organization readiness", () => {+ const apiResultSet = mocks.queryResultSets[3] as [+ { data: Array<Record<string, unknown>> },+ ];+ apiResultSet[0].data = [+ {+ projectId: "project-1",+ entrypoint: "publicapi: GET /api/public/traces",+ count: 4,+ lastSeen: "2026-07-23T10:00:00Z",+ callers: [+ {+ userAgent: "codex-cli/1.2.3",+ count: 4,+ lastSeen: "2026-07-23T10:00:00Z",+ },+ ],+ },+ ];++ const { result } = renderHook(() =>+ useAccountV4MigrationData({+ organizations: [+ {+ id: "org-1",+ name: "Organization",+ projects: [{ id: "project-1", name: "Project" }],+ },+ ],+ enabled: true,+ }),+ );++ expect(result.current.get("project-1")?.apis).toEqual({+ status: "loaded",+ count: 0,+ });+ });+});++describe("project v4 migration data", () => {+ beforeEach(() => {+ mocks.sdkUsageSummaryUseQuery.mockReturnValue(+ loadedQuery({+ experimentInstrumentationMigration: {+ status: "not_required" as const,+ upgradePath: null,+ },+ sdkUsageSeries: [currentSdkSeries],+ }),+ );+ mocks.traceLevelEvalSummaryUseQuery.mockReturnValue(+ loadedQuery({ traceLevelEvalCount: 0 }),+ );+ mocks.legacyApiUsageSummaryUseQuery.mockReturnValue(+ loadedQuery([+ {+ entrypoint: "publicapi: GET /api/public/traces",+ count: 4,+ lastSeen: "2026-07-23T10:00:00Z",+ callers: [+ {+ userAgent: "Claude Code/1.0",+ count: 4,+ lastSeen: "2026-07-23T10:00:00Z",+ },+ ],+ },+ ]),+ );+ mocks.summaryUseQuery.mockReturnValue(+ loadedQuery({+ legacyIntegrationCount: 0,+ legacyIntegrations: {+ posthog: false,+ mixpanel: false,+ blobStorage: false,+ },+ }),+ );+ });++ it("excludes agent-only API usage from readiness but preserves its evidence", () => {+ const { result } = renderHook(() =>+ useProjectV4MigrationData({ projectId: "project-1", enabled: true }),+ );++ expect(result.current.apis).toEqual({ status: "loaded", count: 0 });+ expect(result.current.apiUsage).toHaveLength(1);+ });});describe("migration actions", () => {diff --git a/web/src/features/v4-migration/hooks/useV4MigrationData.ts b/web/src/features/v4-migration/hooks/useV4MigrationData.tsindex c98c4c87d7..729e7b93f9 100644--- a/web/src/features/v4-migration/hooks/useV4MigrationData.ts+++ b/web/src/features/v4-migration/hooks/useV4MigrationData.ts@@ -1,6 +1,7 @@import { api } from "@/src/utils/api";import {- countLegacyApiEntrypoints,+ countActionableLegacyApiEntrypoints,+ isActionableLegacyApiUsage,normalizeLegacyApiEntrypoint,} from "@/src/features/v4/utils";import {@@ -109,7 +110,7 @@ export function useAccountV4MigrationData(params: {?.experimentInstrumentationMigration.status ?? "not_required",),apis: getMigrationCountState(apiQuery, (rows) => {- return countLegacyApiEntrypoints(+ return countActionableLegacyApiEntrypoints(rows.filter((row) => row.projectId === project.id),);}),@@ -264,7 +265,10 @@ export function useProjectV4MigrationData(params: {),experimentInstrumentationUpgradePath:sdkSummary?.experimentInstrumentationMigration.upgradePath ?? null,- apis: getMigrationCountState(apiQuery, () => apiUsage.length),+ apis: getMigrationCountState(+ apiQuery,+ () => apiUsage.filter(isActionableLegacyApiUsage).length,+ ),exports: getMigrationCountState(integrationQuery,(data) => data.legacyIntegrationCount,diff --git a/web/src/features/v4/server/v4TransitionService.ts b/web/src/features/v4/server/v4TransitionService.tsindex 283d2fc49f..cdb2aa4100 100644--- a/web/src/features/v4/server/v4TransitionService.ts+++ b/web/src/features/v4/server/v4TransitionService.ts@@ -23,6 +23,7 @@ import {getSdkUsageSummaries,getSdkUsageSeriesByProject,} from "@/src/features/v4/server/v4TransitionSdkUsage";+import { isActionableLegacyApiUsage } from "@/src/features/v4/utils";export { getSdkUsageSummaries, getLegacyApiUsageSummaries };@@ -313,7 +314,9 @@ export const getMigrationActions = async ({apisActionNeeded:apiBlob === null? null- : trimLegacyApiUsageRows(apiBlob.rows, nowMs).length > 0,+ : trimLegacyApiUsageRows(apiBlob.rows, nowMs).some(+ isActionableLegacyApiUsage,+ ),evalsActionNeeded: (evalSummaries[0]?.traceLevelEvalCount ?? 0) > 0,exportsActionNeeded:(integrationSummaries[0]?.legacyIntegrationCount ?? 0) > 0,diff --git a/web/src/features/v4/utils.ts b/web/src/features/v4/utils.tsindex 4ac989d812..50e2efd07b 100644--- a/web/src/features/v4/utils.ts+++ b/web/src/features/v4/utils.ts@@ -1,6 +1,19 @@export const normalizeLegacyApiEntrypoint = (entrypoint: string) =>entrypoint.replace(/^publicapi:\s*/, "");+const NON_ACTIONABLE_API_CALLER_USER_AGENT = /(claude|codex|curl)/i;++export const isActionableLegacyApiUsage = (row: {+ callers?: { userAgent?: string; isOther?: true }[];+}) =>+ !row.callers?.length ||+ row.callers.some(+ (caller) =>+ caller.isOther ||+ !caller.userAgent ||+ !NON_ACTIONABLE_API_CALLER_USER_AGENT.test(caller.userAgent),+ );+export const countLegacyApiEntrypoints = (rows: Array<{ entrypoint: string }> | undefined,): number => {@@ -13,3 +26,13 @@ export const countLegacyApiEntrypoints = (return entrypoints.size;};++export const countActionableLegacyApiEntrypoints = (+ rows:+ | Array<{+ entrypoint: string;+ callers?: { userAgent?: string; isOther?: true }[];+ }>+ | undefined,+): number =>+ countLegacyApiEntrypoints(rows?.filter(isActionableLegacyApiUsage));