Skip to content

🪢 Open source agent evals & observability: Trace, evaluate, and improve LLM applications with one open platform.

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.ts
index 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.tsx
index 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.tsx
index 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&apos;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&apos;ve recently called deprecated endpoints that will stop
+ working after the migration deadline. Please check the{" "}
<ExternalLink
href={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">
<ExternalLink
href={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 ? (
<span
className="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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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));