Mastra Client SDK

The Mastra Client SDK provides a simple and type-safe interface for interacting with your Mastra Server from your client environment.

Usage example

lib/mastra/mastra-client.ts

import { MastraClient } from "@mastra/client-js";

export const mastraClient = new MastraClient({
  baseUrl: "http://localhost:4111/",
});

Parameters

baseUrl:

string

The base URL for the Mastra API. All requests will be sent relative to this URL.

retries?:

number

= 3

The number of times a request will be retried on failure before throwing an error.

backoffMs?:

number

= 300

The initial delay in milliseconds before retrying a failed request. This value is doubled with each retry (exponential backoff).

maxBackoffMs?:

number

= 5000

The maximum backoff time in milliseconds. Prevents retries from waiting too long between attempts.

headers?:

Record<string, string>

An object containing custom HTTP headers to include with every request.

credentials?:

"omit" | "same-origin" | "include"

Credentials mode for requests. See https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials for more info.

Methods

getAgents():

Promise<Record<string, GetAgentResponse>>

Returns all available agent instances.

getAgent(agentId):

Agent

Retrieves a specific agent instance by ID.

getMemoryThreads(params):

Promise<StorageThreadType[]>

Retrieves memory threads for the specified resource and agent. Requires a `resourceId` and an `agentId`.

createMemoryThread(params):

Promise<MemoryThread>

Creates a new memory thread with the given parameters.

getMemoryThread({ threadId, agentId }):

MemoryThread

Fetches a specific memory thread by ID.

saveMessageToMemory(params):

Promise<void>

Saves one or more messages to the memory system.

getMemoryStatus():

Promise<MemoryStatus>

Returns the current status of the memory system.

getTools():

Record<string, Tool>

Returns all available tools.

getTool(toolId):

Tool

Retrieves a specific tool instance by ID.

getWorkflows():

Record<string, Workflow>

Returns all available workflow instances.

getWorkflow(workflowId):

Workflow

Retrieves a specific workflow instance by ID.

getVector(vectorName):

MastraVector

Returns a vector store instance by name.

listLogs(params):

Promise<LogEntry[]>

Fetches system logs matching the provided filters.

getLog(params):

Promise<LogEntry>

Retrieves a specific log entry by ID or filter.

listLogTransports():

string[]

Returns the list of configured log transport types.

getAITrace(traceId):

Promise<AITraceRecord>

Retrieves a specific AI trace by ID, including all its spans and details.

getAITraces(params):

Promise<GetAITracesResponse>

Retrieves paginated list of AI trace root spans with optional filtering. Use getAITrace() to get complete traces with all spans.