---
title: "Reference: Mastra Client SDK | Client SDK"
description: Learn how to interact with Mastra using the client-js SDK.
packages:
  - "@mastra/client-js"
---

# Mastra Client SDK

The Mastra Client SDK provides a simple and type-safe interface for interacting with your [Mastra Server](/docs/v1/deployment/mastra-server) from your client environment.

## Usage example

```typescript title="lib/mastra/mastra-client.ts"
import { MastraClient } from "@mastra/client-js";

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

## Parameters

<PropertiesTable
  content={[
    {
      name: "baseUrl",
      type: "string",
      description:
        "The base URL for the Mastra API. All requests will be sent relative to this URL.",
      isOptional: false,
    },
    {
      name: "retries",
      type: "number",
      description:
        "The number of times a request will be retried on failure before throwing an error.",
      isOptional: true,
      defaultValue: "3",
    },
    {
      name: "backoffMs",
      type: "number",
      description:
        "The initial delay in milliseconds before retrying a failed request. This value is doubled with each retry (exponential backoff).",
      isOptional: true,
      defaultValue: "300",
    },
    {
      name: "maxBackoffMs",
      type: "number",
      description:
        "The maximum backoff time in milliseconds. Prevents retries from waiting too long between attempts.",
      isOptional: true,
      defaultValue: "5000",
    },
    {
      name: "headers",
      type: "Record<string, string>",
      description:
        "An object containing custom HTTP headers to include with every request.",
      isOptional: true,
    },
    {
      name: "credentials",
      type: '"omit" | "same-origin" | "include"',
      description:
        "Credentials mode for requests. See https://developer.mozilla.org/en-US/docs/Web/API/Request/credentials for more info.",
      isOptional: true,
    },
  ]}
/>

## Methods

<PropertiesTable
  content={[
    {
      name: "listAgents()",
      type: "Promise<Record<string, GetAgentResponse>>",
      description: "Returns all available agent instances.",
    },
    {
      name: "getAgent(agentId)",
      type: "Agent",
      description: "Retrieves a specific agent instance by ID.",
    },
    {
      name: "getMemoryThreads(params)",
      type: "Promise<StorageThreadType[]>",
      description:
        "Retrieves memory threads for the specified resource and agent. Requires a `resourceId` and an `agentId`.",
    },
    {
      name: "createMemoryThread(params)",
      type: "Promise<MemoryThread>",
      description: "Creates a new memory thread with the given parameters.",
    },
    {
      name: "getMemoryThread({ threadId, agentId })",
      type: "MemoryThread",
      description: "Fetches a specific memory thread by ID.",
    },
    {
      name: "saveMessageToMemory(params)",
      type: "Promise<{ messages: (MastraMessageV1 | MastraDBMessage)[] }>",
      description: "Saves one or more messages to the memory system. Returns the saved messages.",
    },
    {
      name: "getMemoryStatus()",
      type: "Promise<MemoryStatus>",
      description: "Returns the current status of the memory system.",
    },
    {
      name: "listTools()",
      type: "Record<string, Tool>",
      description: "Returns all available tools.",
    },
    {
      name: "getTool(toolId)",
      type: "Tool",
      description: "Retrieves a specific tool instance by ID.",
    },
    {
      name: "listWorkflows()",
      type: "Record<string, Workflow>",
      description: "Returns all available workflow instances.",
    },
    {
      name: "getWorkflow(workflowId)",
      type: "Workflow",
      description: "Retrieves a specific workflow instance by ID.",
    },
    {
      name: "getVector(vectorName)",
      type: "MastraVector",
      description: "Returns a vector store instance by name.",
    },
    {
      name: "listLogs(params)",
      type: "Promise<LogEntry[]>",
      description: "Fetches system logs matching the provided filters.",
    },
    {
      name: "getLog(params)",
      type: "Promise<LogEntry>",
      description: "Retrieves a specific log entry by ID or filter.",
    },
    {
      name: "listLogTransports()",
      type: "string[]",
      description: "Returns the list of configured log transport types.",
    },
    {
      name: "getTrace(traceId)",
      type: "Promise<TraceRecord>",
      description:
        "Retrieves a specific trace by ID, including all its spans and details.",
    },
    {
      name: "getTraces(params)",
      type: "Promise<GetTracesResponse>",
      description:
        "Retrieves paginated list of trace root spans with optional filtering. Use getTrace() to get complete traces with all spans.",
    },
  ]}
/>
