---
title: "Client SDK | v1 Migration Guide"
description: "Learn how to migrate client SDK changes when upgrading to v1."
---

# Client SDK

Client SDK changes align with server-side API updates including renamed utilities, updated pagination, and type naming conventions.

## Changed

### Client SDK types from `Get*` to `List*`

Client SDK types have been renamed from `Get*` to `List*` pattern. This change aligns type names with the method naming convention.

To migrate, update type imports to use the new naming pattern.

```diff
- import type {
-   GetWorkflowRunsParams,
-   GetWorkflowRunsResponse,
-   GetMemoryThreadParams,
- } from '@mastra/client-js';
+ import type {
+   ListWorkflowRunsParams,
+   ListWorkflowRunsResponse,
+   ListMemoryThreadsParams,
+ } from '@mastra/client-js';
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/client-sdk-types .
```

:::

### Pagination parameters from `offset/limit` to `page/perPage`

All client SDK methods that used `offset/limit` now use `page/perPage`. This change provides a more intuitive pagination model aligned with web pagination patterns.

To migrate, update pagination parameters in all client SDK method calls. Example:

```diff
  client.memory.listMessages({
    threadId: 'thread-123',
-   offset: 0,
-   limit: 20,
+   page: 0,
+   perPage: 20,
  });
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/client-offset-limit .
```

:::

### `getMemoryThread` parameter structure

The `getMemoryThread` method parameter structure has been updated. This change provides a more consistent API across memory methods.

To migrate, update the method call with the new parameter structure. Check the updated API documentation for the specific changes.

```diff
- const thread = await client.getMemoryThread(threadId, agentId);
+ const thread = await client.getMemoryThread({ threadId, agentId });
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/client-get-memory-thread .
```

:::

### Unified `runById` API for workflow runs

The `runById()` method now returns a unified `WorkflowState` object containing both metadata (runId, workflowName, resourceId, createdAt, updatedAt) and processed execution state (status, result, error, payload, steps). This unifies the previously separate `runById()` and `runExecutionResult()` methods.

The method also accepts an options object with optional `fields` and `withNestedWorkflows` parameters for performance optimization.

```diff
  const workflow = client.getWorkflow('my-workflow');

- // Previously: runById returned raw WorkflowRun with snapshot
- const run = await workflow.runById(runId, requestContext);
- // Separately: runExecutionResult returned processed execution state
- const result = await workflow.runExecutionResult(runId);

+ // Now: Single method returns unified WorkflowState
+ const run = await workflow.runById(runId, {
+   requestContext,  // Optional request context
+   fields: ['status', 'result'],  // Optional: request only specific fields
+   withNestedWorkflows: false,  // Optional: skip nested workflow data for performance
+ });
+ // Returns: { runId, workflowName, resourceId, createdAt, updatedAt, status, result, error, payload, steps }
```

## Removed

### `runExecutionResult` method and `GetWorkflowRunExecutionResultResponse` type

The `runExecutionResult()` method and `GetWorkflowRunExecutionResultResponse` type have been removed from `@mastra/client-js`. The `/execution-result` API endpoints have also been removed.

To migrate, use `runById()` instead, which now returns the same unified `WorkflowState` with both metadata and processed execution state.

```diff
- import type { GetWorkflowRunExecutionResultResponse } from '@mastra/client-js';
-
- const workflow = client.getWorkflow('my-workflow');
- const result = await workflow.runExecutionResult(runId);

+ const workflow = client.getWorkflow('my-workflow');
+ const result = await workflow.runById(runId);
+ // Or with options for performance optimization:
+ const result = await workflow.runById(runId, {
+   fields: ['status', 'result'],  // Only fetch specific fields
+   withNestedWorkflows: false,     // Skip expensive nested workflow data
+ });
```

### `toAISdkFormat` function

The `toAISdkFormat()` function has been removed from `@mastra/ai-sdk`. This change provides clearer naming for stream conversion utilities.

To migrate, use `toAISdkStream()` instead.

```diff
- import { toAISdkFormat } from '@mastra/ai-sdk';
- const stream = toAISdkFormat(agentStream, { from: 'agent' });
+ import { toAISdkStream } from '@mastra/ai-sdk';
+ const stream = toAISdkStream(agentStream, { from: 'agent' });
```

:::tip[Codemod]

You can use Mastra's codemod CLI to update your code automatically:

```shell
npx @mastra/codemod@beta v1/client-to-ai-sdk-format .
```

:::

### Network memory methods

Network memory methods have been removed from `@mastra/client-js`. The `NetworkMemoryThread` class and all network memory-related methods are no longer available. This change simplifies the memory API by removing specialized network memory functionality.

To migrate, use regular memory APIs instead of network memory.

```diff
- import { MastraClient } from '@mastra/client-js';
- 
- const client = new MastraClient({ baseUrl: '...' });
- const networkThread = client.networkMemory.getThread('thread-id');
- const networkThread = client.memory.networkThread('thread-id', 'network-id');
- await networkThread.get();
- await networkThread.getMessages();

+ // Use regular memory thread APIs instead
+ const client = new MastraClient({ baseUrl: '...' });
+ const thread = client.memory.getThread('thread-id');
+ await thread.get();
+ const messages = await thread.listMessages();
```

### Watch-related types

Watch-related types have been removed from `@mastra/client-js`. This includes `WorkflowWatchResult`, `WatchEvent`, and related types. This change reflects the removal of the watch API in favor of streaming.

To migrate, use workflow streaming APIs instead of watch.

```diff
- import type { WorkflowWatchResult, WatchEvent } from '@mastra/client-js';
- 
- const workflow = client.getWorkflow('my-workflow');
- const run = await workflow.createRun();
- await run.watch((event: WatchEvent) => {
-   console.log('Event:', event);
- });

+ const workflow = client.getWorkflow('my-workflow');
+ const run = await workflow.createRun();
+ const stream = await run.stream({ inputData: { ... } });
+ for await (const chunk of stream) {
+   console.log('Event:', chunk);
+ }
```

### Run-related methods cannot be called directly on workflow instance

Run-related methods cannot be called directly on workflow instance. You need to create a run instance first using `createRun()` method.


```diff
- const result = await workflow.start({ runId: '123', inputData: { ... } });
+ const run = await workflow.createRun({ runId: '123' });
+ const result = await run.start({ inputData: { ... } });
```

```diff
- const result = await workflow.stream({ runId: '123', inputData: { ... } });
+ const run = await workflow.createRun({ runId: '123' });
+ const stream = await run.stream({ inputData: { ... } });
```

### `streamVNext`, `resumeStreamVNext`, and `observeStreamVNext` methods

The experimental `streamVNext()`, `resumeStreamVNext()`, and `observeStreamVNext()` methods have been removed. These methods are now the standard implementation with updated event structures and return types.

To migrate, use the standard `stream()`, `resumeStream()`, and `observeStream()` methods instead.

```diff
+ const run = await workflow.createRun({ runId: '123' });
- const stream = await run.streamVNext({ inputData: { ... } });
+ const stream = await run.stream({ inputData: { ... } });
```

### Deprecated stream endpoints

Some stream endpoints are deprecated and will be removed. The `/api/agents/:agentId/stream/vnext` endpoint returns 410 Gone, and `/api/agents/:agentId/stream/ui` is deprecated. This change consolidates on standard streaming endpoints.

To migrate, use the standard stream endpoint or `@mastra/ai-sdk` for UI message transformations.

```diff
- const response = await fetch('/api/agents/my-agent/stream/vnext', {
-   method: 'POST',
-   body: JSON.stringify({ messages: [...] }),
- });

+ const response = await fetch('/api/agents/my-agent/stream', {
+   method: 'POST',
+   body: JSON.stringify({ messages: [...] }),
+ });
+ 
+ // Or use @mastra/ai-sdk for UI message transformations
```

### Network memory API endpoints

Network memory API endpoints have been removed including `/api/memory/network/*`. This change simplifies the memory API surface.

To migrate, use regular memory API endpoints.

```diff
- const networkThread = await fetch('/api/memory/network/threads/thread-123');
+ const thread = await fetch('/api/memory/threads/thread-123');
```

### Eval-related client SDK types

Several eval-related types have been removed from the client SDK including `GetEvalsByAgentIdResponse`, `GetTelemetryResponse`, and `GetTelemetryParams`. This change reflects the removal of legacy evals functionality.

To migrate, use the new scorers API instead of legacy evals.
