Class: MastraPluginClient

@mastra/client-js MastraClient extended with the Mastra plugin’s custom routes. One client drives everything the chat UI needs:

Conversation streaming through Mastra’s official AI SDK chatRoute and the browser-native AI SDK DefaultChatTransport.
Native Mastra memory history and thread management, plus the model catalogue (models), Genie starter prompts (suggestions), MLflow feedback logging (feedback), and inline embed resolution (chart / statement) over the plugin’s own routes - all derived from basePath + routes.MASTRA_ROUTES.

Built from the plugin’s published clientConfig() payload (MastraClientConfig). credentials: "include" is set once at construction so the session cookie (which pins the server-side thread id) travels with every request, streaming included.

Extends

MastraClient

Constructors

Constructor

new MastraPluginClient(config): MastraPluginClient

Parameters

config

agents

string[] = ...

backgroundTurns?

boolean = ...

basePath

string = ...

chatAlwaysAvailable?

boolean = ...

defaultAgent

string = ...

feedbackEnabled?

boolean = ...

Returns

MastraPluginClient

Overrides

MastraClient.constructor

Properties

agents

readonly agents: readonly string[]

Registered agent ids, surfaced for pickers.

apiPrefix

protected readonly apiPrefix: string

Inherited from

MastraClient.apiPrefix

backgroundTurns

readonly backgroundTurns: boolean

Whether turns continue server-side after the initiating stream disconnects.

basePath

readonly basePath: string

Plugin mount prefix (/api/<plugin-name>); all custom routes derive from it.

channels

readonly channels: Channels

Inherited from

MastraClient.channels

chatAlwaysAvailable

readonly chatAlwaysAvailable: boolean

Whether the agents run their Databricks calls as the app service principal rather than on-behalf-of the signed-in user. When true the chat works for any caller who can open the app, so a UI that hides chat when the OBO token is absent should show it regardless. false (the default "user" identity mode) keeps the OBO-gated behavior.

conversations

readonly conversations: Conversations

Inherited from

MastraClient.conversations

defaultAgent

readonly defaultAgent: string

Agent the bare (un-suffixed) routes resolve to.

feedbackEnabled

readonly feedbackEnabled: boolean

Whether the server can log feedback to MLflow. When false, the chat UI hides thumbs / comment controls and feedback would be rejected server-side, so callers gate on this before offering feedback affordances.

options

readonly options: ClientOptions

Inherited from

MastraClient.options

responses

readonly responses: Responses

Inherited from

MastraClient.responses

Methods

abortAgentRun()

abortAgentRun(params): Promise<boolean>

Explicitly stop one background agent run on the server.

Parameters

params

agentId

string

runId

string

signal?

AbortSignal

threadId?

string

Returns

Promise<boolean>

addDatasetItem()

addDatasetItem(params): Promise<{ createdAt: string; datasetId: string; datasetVersion: number; expectedTrajectory?: unknown; externalId?: string | null; groundTruth?: unknown; id: string; input: unknown; metadata?: {[key: string]: unknown; } | null; requestContext?: {[key: string]: unknown; } | null; scorerIds?: string[] | null; source?: { referenceId?: string; type: "csv" | "json" | "trace" | "llm" | "experiment-result" | "candidate-screener"; } | null; toolMocks?: object[] | null; unmockedToolPolicy?: "allow" | "deny" | null; updatedAt: string; }>

Adds an item to a dataset

Parameters

params

AddDatasetItemParams

Returns

Promise<{ createdAt: string; datasetId: string; datasetVersion: number; expectedTrajectory?: unknown; externalId?: string | null; groundTruth?: unknown; id: string; input: unknown; metadata?: {[key: string]: unknown; } | null; requestContext?: {[key: string]: unknown; } | null; scorerIds?: string[] | null; source?: { referenceId?: string; type: "csv" | "json" | "trace" | "llm" | "experiment-result" | "candidate-screener"; } | null; toolMocks?: object[] | null; unmockedToolPolicy?: "allow" | "deny" | null; updatedAt: string; }>

Inherited from

MastraClient.addDatasetItem

approveToolCallStream()

approveToolCallStream(agentId, params): Promise<MastraStreamResponse>

Resume a suspended requireApproval tool through the same official chat route using Mastra’s native resumeData contract.

Parameters

agentId

string

params

requestContext?

MastraRequestContextSnapshot

runId

string

signal?

AbortSignal

threadId?

string

toolCallId

string

Returns

Promise<MastraStreamResponse>

awaitBufferStatus()

awaitBufferStatus(params): Promise<{ record: { activeObservations: string; bufferedObservationChunks?: object[]; bufferedObservations?: string; bufferedReflection?: string; config: {[key: string]: unknown; }; createdAt: string; generationCount: number; id: string; isObserving: boolean; isReflecting: boolean; lastObservedAt?: string; metadata?: {[key: string]: unknown; }; observationTokenCount: number; originType: "initial" | "observation" | "reflection"; pendingMessageTokens: number; resourceId: string; scope: "thread" | "resource"; threadId: string | null; totalTokensObserved: number; updatedAt: string; } | null; }>

Blocks until any in-flight observational memory buffering completes, then returns the updated record

Parameters

params

AwaitBufferStatusParams

Parameters containing agentId, resourceId, threadId

Returns

Promise<{ record: { activeObservations: string; bufferedObservationChunks?: object[]; bufferedObservations?: string; bufferedReflection?: string; config: {[key: string]: unknown; }; createdAt: string; generationCount: number; id: string; isObserving: boolean; isReflecting: boolean; lastObservedAt?: string; metadata?: {[key: string]: unknown; }; observationTokenCount: number; originType: "initial" | "observation" | "reflection"; pendingMessageTokens: number; resourceId: string; scope: "thread" | "resource"; threadId: string | null; totalTokensObserved: number; updatedAt: string; } | null; }>

Promise containing the updated OM record after buffering completes

Inherited from

MastraClient.awaitBufferStatus

batchDeleteDatasetItems()

batchDeleteDatasetItems(params): Promise<{ deletedCount: number; success: boolean; }>

Batch deletes items from a dataset

Parameters

params

BatchDeleteDatasetItemsParams

Returns

Promise<{ deletedCount: number; success: boolean; }>

Inherited from

MastraClient.batchDeleteDatasetItems

batchInsertDatasetItems()

batchInsertDatasetItems(params): Promise<{ count: number; items: object[]; }>

Batch inserts items to a dataset

Parameters

params

BatchInsertDatasetItemsParams

Returns

Promise<{ count: number; items: object[]; }>

Inherited from

MastraClient.batchInsertDatasetItems

chart()

chart(id, signal?): Promise<{ chartId: string; error?: string; result?: { chartType: "custom" | "bar" | "horizontalBar" | "line" | "area" | "combo" | "waterfall" | "scatter" | "heatmap" | "radar" | "pie" | "funnel" | "treemap"; option: Record<string, unknown>; }; } | undefined>

Resolve a [chart:<id>] marker from GET ${basePath}/embed/chart/:id. The chart planner runs in the background, so the server long-polls the cache and returns the settled entry in one response. A 404 (unknown / expired id) resolves to undefined so the slot renders nothing.

Parameters

id

string

signal?

AbortSignal

Returns

Promise<{ chartId: string; error?: string; result?: { chartType: "custom" | "bar" | "horizontalBar" | "line" | "area" | "combo" | "waterfall" | "scatter" | "heatmap" | "radar" | "pie" | "funnel" | "treemap"; option: Record<string, unknown>; }; } | undefined>

clearHistory()

clearHistory(options): Promise<void>

Delete one native memory thread so the same id can start cleanly.

Parameters

options

agentId?

string

signal?

AbortSignal

threadId

string

Returns

Promise<void>

clusterFailures()

clusterFailures(params): Promise<{ clusters: object[]; proposedTags?: object[]; }>

Cluster experiment failures using AI to identify common failure patterns.

Parameters

params

PostDatasetsClusterFailures_Body

Returns

Promise<{ clusters: object[]; proposedTags?: object[]; }>

Inherited from

MastraClient.clusterFailures

compareExperiments()

compareExperiments(params): Promise<{ baselineId: string; items: object[]; }>

Compares two dataset experiments for regression detection

Parameters

params

CompareExperimentsParams

Returns

Promise<{ baselineId: string; items: object[]; }>

Inherited from

MastraClient.compareExperiments

createDataset()

createDataset(params): Promise<{ createdAt: string; description?: string | null; groundTruthSchema?: {[key: string]: unknown; }; id: string; inputSchema?: {[key: string]: unknown; }; metadata?: {[key: string]: unknown; } | null; name: string; requestContextSchema?: {[key: string]: unknown; }; scorerIds?: string[] | null; tags?: string[] | null; targetIds?: string[] | null; targetType?: string | null; updatedAt: string; version: number; }>

Creates a new dataset

Parameters

params

CreateDatasetParams

Returns

Promise<{ createdAt: string; description?: string | null; groundTruthSchema?: {[key: string]: unknown; }; id: string; inputSchema?: {[key: string]: unknown; }; metadata?: {[key: string]: unknown; } | null; name: string; requestContextSchema?: {[key: string]: unknown; }; scorerIds?: string[] | null; tags?: string[] | null; targetIds?: string[] | null; targetType?: string | null; updatedAt: string; version: number; }>

Inherited from

MastraClient.createDataset

createDatasetExperiment()

createDatasetExperiment(params): Promise<{ completedAt: string | null; datasetVersion?: number; experimentId: string; failedCount: number; results: object[]; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; totalItems: number; }>

Creates an experiment without starting the in-process runner, so the caller drives the loop (e.g. a Temporal workflow). With a target, execute items server-side via runExperimentItem; without one, ingest results via submitExperimentResult. Idempotent when a caller-supplied id is provided.

Parameters

params

CreateDatasetExperimentParams

Returns

Promise<{ completedAt: string | null; datasetVersion?: number; experimentId: string; failedCount: number; results: object[]; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; totalItems: number; }>

Inherited from

MastraClient.createDatasetExperiment

createFeedback()

createFeedback(params): Promise<{ success: boolean; }>

Creates a single feedback record in the observability store.

Parameters

params

PostObservabilityFeedback_Body

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.createFeedback

createMemoryThread()

createMemoryThread(params): Promise<{ createdAt: string; id: string; metadata?: {[key: string]: unknown; }; resourceId: string; title?: string; updatedAt: string; }>

Creates a new memory thread

Parameters

params

CreateMemoryThreadParams

Parameters for creating the memory thread including optional request context

Returns

Promise<{ createdAt: string; id: string; metadata?: {[key: string]: unknown; }; resourceId: string; title?: string; updatedAt: string; }>

Promise containing the created memory thread

Inherited from

MastraClient.createMemoryThread

createSchedule()

createSchedule(options): Promise<ScheduleResponse>

Creates a schedule. Pass agentId (plus prompt) to schedule an agent, or workflowId (plus optional inputData) to schedule a workflow. By default each call creates a new schedule with a random id (agent_<uuid> for agents, schedule_<uuid> for workflows) — pass id to choose a stable id instead; creating one with an id that already exists throws.

Trigger (fire) history is read through listScheduleTriggers(schedule.id).

Parameters

options

CreateScheduleInput

Returns

Promise<ScheduleResponse>

Inherited from

MastraClient.createSchedule

createScore()

createScore(params): Promise<{ success: boolean; }>

Creates a single score record in the observability store.

Parameters

params

PostObservabilityScores_Body

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.createScore

createStoredAgent()

createStoredAgent(params): Promise<{ activeVersionId?: string; agents?: object[] | {[key: string]: object; }; author?: { avatarUrl?: string; email?: string; id: string; name?: string; }; authorId?: string; browser?: boolean | { config: { headless?: boolean; provider: string; screencast?: { everyNthFrame?: number; format?: "jpeg" | "png"; maxHeight?: number; maxWidth?: number; quality?: number; }; timeout?: number; viewport?: { height: number; width: number; }; }; type: "inline"; } | object[] | null; createdAt: string; defaultOptions?: {[key: string]: unknown; activeTools?: string[]; autoResumeSuspendedTools?: boolean; eagerToolExecution?: boolean; includeRawChunks?: boolean; maxProcessorRetries?: number; maxSteps?: number; modelSettings?: { frequencyPenalty?: number; maxRetries?: number; maxTokens?: number; presencePenalty?: number; seed?: number; stopSequences?: string[]; temperature?: number; topK?: number; topP?: number; }; requireToolApproval?: boolean; returnScorerData?: boolean; runId?: string; savePerStep?: boolean; toolCallConcurrency?: number | { limit?: number; strategy?: "available" | "called"; }; toolChoice?: "none" | "auto" | "required" | { toolName: string; type: "tool"; }; tracingOptions?: { attributes?: {[key: string]: unknown; }; spanId?: string; traceId?: string; traceName?: string; }; } | object[]; description?: string; durable?: boolean | { cleanupTimeoutMs?: number; maxSteps?: number; }; favoriteCount?: number; id: string; inputProcessors?: { steps: ({ step: { config: {[key: string]: unknown; }; enabledPhases: ("processInput" | "processInputStep" | "processOutputStream" | "processOutputResult" | "processOutputStep" | "processToolResult")[]; id: string; providerId: string; }; type: "step"; } | { branches: ({ step: …; type: …; } | { branches: …; type: …; } | { conditions: …; type: …; })[][]; type: "parallel"; } | { conditions: object[]; type: "conditional"; })[]; } | object[]; instructions: string | ({ content: string; type: "text"; } | { id: string; type: "prompt_block_ref"; } | { content: string; rules?: { conditions: ({ field: …; operator: …; value?: …; } | { conditions: …; operator: …; })[]; operator: "AND" | "OR"; }; type: "prompt_block"; })[]; integrationTools?: {[key: string]: object; } | object[]; isFavorited?: boolean; mcpClients?: {[key: string]: object; } | object[]; memory?: { embedder?: string; embedderOptions?: {[key: string]: unknown; }; observationalMemory?: boolean | { model?: string; observation?: { blockAfter?: number; bufferActivation?: number; bufferTokens?: number | false; maxTokensPerBatch?: number; messageTokens?: number; model?: string; modelSettings?: {[key: string]: unknown; }; providerOptions?: {[key: string]: … | …; }; }; reflection?: { blockAfter?: number; bufferActivation?: number; model?: string; modelSettings?: {[key: string]: unknown; }; observationTokens?: number; providerOptions?: {[key: string]: … | …; }; }; scope?: "thread" | "resource"; shareTokenBudget?: boolean; }; options?: { generateTitle?: boolean | { emitEvent?: boolean; instructions?: string; minMessages?: number; model?: string; }; lastMessages?: number | false; messageHistory?: { atMaxRemoveTokens?: number; maxTokens: number; }; readOnly?: boolean; semanticRecall?: boolean | { indexName?: string; messageRange: number | { after: number; before: number; }; scope?: "thread" | "resource"; threshold?: number; topK: number; }; }; vector?: string | false; } | object[]; metadata?: {[key: string]: unknown; }; model: {[key: string]: unknown; name: string; provider: string; } | object[]; name: string; outputProcessors?: { steps: ({ step: { config: {[key: string]: unknown; }; enabledPhases: ("processInput" | "processInputStep" | "processOutputStream" | "processOutputResult" | "processOutputStep" | "processToolResult")[]; id: string; providerId: string; }; type: "step"; } | { branches: ({ step: …; type: …; } | { branches: …; type: …; } | { conditions: …; type: …; })[][]; type: "parallel"; } | { conditions: object[]; type: "conditional"; })[]; } | object[]; requestContextSchema?: {[key: string]: unknown; }; scorers?: {[key: string]: object; } | object[]; skills?: {[key: string]: object; } | object[]; status: string; toolProviders?: {[key: string]: object; } | object[]; tools?: {[key: string]: object; } | object[]; updatedAt: string; visibility?: "public" | "private"; workflows?: object[] | {[key: string]: object; }; workspace?: { type: "id"; workspaceId: string; } | { config: { autoSync?: boolean; description?: string; filesystem?: { config: {[key: string]: unknown; }; provider: string; }; mounts?: {[key: string]: object; }; name: string; operationTimeout?: number; sandbox?: { config: {[key: string]: unknown; }; provider: string; }; search?: { autoIndexPaths?: string[]; bm25?: boolean | { b?: number; k1?: number; }; embedderConfig?: {[key: string]: unknown; }; embedderModel?: string; embedderProvider?: string; searchIndexName?: string; vectorConfig?: {[key: string]: unknown; }; vectorProvider?: string; }; skills?: string[]; tools?: { enabled?: boolean; requireApproval?: boolean; tools?: {[key: string]: object; }; }; }; type: "inline"; } | { config: {[key: string]: unknown; }; provider: string; type: "provider"; } | object[]; }>

Creates a new stored agent

Parameters

params

Agent configuration including id, name, instructions, model, etc.

agents?

{[key: string]: object; } | object[]

Agent keys with optional per-agent config — static or conditional

authorId?

string

Author identifier for multi-tenant filtering

autoPublish?

boolean

Publish the initial version so the agent resolves at status=“published”. Defaults to true when omitted. Pass false to stage the agent as an unpublished draft — useful when overriding a code-defined agent, whose code definition keeps serving traffic until the override is published.

browser?

boolean | { config: { headless?: boolean; provider: string; screencast?: { everyNthFrame?: number; format?: "jpeg" | "png"; maxHeight?: number; maxWidth?: number; quality?: number; }; timeout?: number; viewport?: { height: number; width: number; }; }; type: "inline"; } | object[] | null

Browser configuration — object config, true (apply default), false/null (disable)

defaultOptions?

{[key: string]: unknown; activeTools?: string[]; autoResumeSuspendedTools?: boolean; eagerToolExecution?: boolean; includeRawChunks?: boolean; maxProcessorRetries?: number; maxSteps?: number; modelSettings?: { frequencyPenalty?: number; maxRetries?: number; maxTokens?: number; presencePenalty?: number; seed?: number; stopSequences?: string[]; temperature?: number; topK?: number; topP?: number; }; requireToolApproval?: boolean; returnScorerData?: boolean; runId?: string; savePerStep?: boolean; toolCallConcurrency?: number | { limit?: number; strategy?: "available" | "called"; }; toolChoice?: "none" | "auto" | "required" | { toolName: string; type: "tool"; }; tracingOptions?: { attributes?: {[key: string]: unknown; }; spanId?: string; traceId?: string; traceName?: string; }; } | object[]

Default options for generate/stream calls — static or conditional

description?

string

Description of the agent

durable?

boolean | { cleanupTimeoutMs?: number; maxSteps?: number; }

Opt this agent into durable execution when it is hydrated. Cache and pubsub are inherited from the Mastra instance; without distributed backends durability is process-local. Does not enable automatic recovery — that stays recovery.durableAgents.

id?

string

Unique identifier for the agent. If not provided, derived from name.

inputProcessors?

{ steps: ({ step: { config: {[key: string]: unknown; }; enabledPhases: ("processInput" | "processInputStep" | "processOutputStream" | "processOutputResult" | "processOutputStep" | "processToolResult")[]; id: string; providerId: string; }; type: "step"; } | { branches: ({ step: { config: …; enabledPhases: …; id: …; providerId: …; }; type: "step"; } | { branches: …[]; type: "parallel"; } | { conditions: …[]; type: "conditional"; })[][]; type: "parallel"; } | { conditions: object[]; type: "conditional"; })[]; } | object[]

Input processor graph — static or conditional

instructions

string | ({ content: string; type: "text"; } | { id: string; type: "prompt_block_ref"; } | { content: string; rules?: { conditions: ({ field: string; operator: InputShared_Type_31; value?: unknown; } | { conditions: …[]; operator: … | …; })[]; operator: "AND" | "OR"; }; type: "prompt_block"; })[]

System instructions for the agent (string or array of instruction blocks)

integrationTools?

{[key: string]: object; } | object[]

Map of tool provider IDs to their tool configurations — static or conditional

mcpClients?

object[] | {[key: string]: object; }

Map of stored MCP client IDs to their tool configurations — static or conditional

memory?

{ embedder?: string; embedderOptions?: {[key: string]: unknown; }; observationalMemory?: boolean | { model?: string; observation?: { blockAfter?: number; bufferActivation?: number; bufferTokens?: number | false; maxTokensPerBatch?: number; messageTokens?: number; model?: string; modelSettings?: {[key: string]: unknown; }; providerOptions?: {[key: string]: {[key: …]: …; } | undefined; }; }; reflection?: { blockAfter?: number; bufferActivation?: number; model?: string; modelSettings?: {[key: string]: unknown; }; observationTokens?: number; providerOptions?: {[key: string]: {[key: …]: …; } | undefined; }; }; scope?: "thread" | "resource"; shareTokenBudget?: boolean; }; options?: { generateTitle?: boolean | { emitEvent?: boolean; instructions?: string; minMessages?: number; model?: string; }; lastMessages?: number | false; messageHistory?: { atMaxRemoveTokens?: number; maxTokens: number; }; readOnly?: boolean; semanticRecall?: boolean | { indexName?: string; messageRange: number | { after: number; before: number; }; scope?: "thread" | "resource"; threshold?: number; topK: number; }; }; vector?: string | false; } | object[]

Memory configuration — static or conditional

metadata?

{[key: string]: unknown; }

Additional metadata for the agent

model?

{[key: string]: unknown; name: string; provider: string; } | object[]

Model configuration — static value or array of conditional variants. When omitted, the builder default model is applied server-side.

name

string

Name of the agent

outputProcessors?

Output processor graph — static or conditional

requestContextSchema?

{[key: string]: unknown; }

JSON Schema defining valid request context variables for conditional rule evaluation

scorers?

{[key: string]: object; } | object[]

Scorer keys with optional sampling config — static or conditional

skills?

{[key: string]: object; } | object[]

Skill IDs mapped to per-skill config — static or conditional

toolProviders?

{[key: string]: object; } | object[]

Tool provider connections and per-tool config (provider-agnostic). Coexists with the deprecated integrationTools field.

tools?

{[key: string]: object; } | object[]

Tool keys mapped to per-tool config — static or conditional

visibility?

"public" | "private"

Agent visibility: private (owner/admin only) or public (any reader)

workflows?

{[key: string]: object; } | object[]

Workflow keys with optional per-workflow config — static or conditional

workspace?

{ type: "id"; workspaceId: string; } | { config: { autoSync?: boolean; description?: string; filesystem?: { config: {[key: string]: unknown; }; provider: string; }; mounts?: {[key: string]: object; }; name: string; operationTimeout?: number; sandbox?: { config: {[key: string]: unknown; }; provider: string; }; search?: { autoIndexPaths?: string[]; bm25?: boolean | { b?: number; k1?: number; }; embedderConfig?: {[key: string]: unknown; }; embedderModel?: string; embedderProvider?: string; searchIndexName?: string; vectorConfig?: {[key: string]: unknown; }; vectorProvider?: string; }; skills?: string[]; tools?: { enabled?: boolean; requireApproval?: boolean; tools?: {[key: string]: object; }; }; }; type: "inline"; } | { config: {[key: string]: unknown; }; provider: string; type: "provider"; } | object[]

Workspace reference (stored ID or inline config) — static or conditional

Returns

Promise<{ activeVersionId?: string; agents?: object[] | {[key: string]: object; }; author?: { avatarUrl?: string; email?: string; id: string; name?: string; }; authorId?: string; browser?: boolean | { config: { headless?: boolean; provider: string; screencast?: { everyNthFrame?: number; format?: "jpeg" | "png"; maxHeight?: number; maxWidth?: number; quality?: number; }; timeout?: number; viewport?: { height: number; width: number; }; }; type: "inline"; } | object[] | null; createdAt: string; defaultOptions?: {[key: string]: unknown; activeTools?: string[]; autoResumeSuspendedTools?: boolean; eagerToolExecution?: boolean; includeRawChunks?: boolean; maxProcessorRetries?: number; maxSteps?: number; modelSettings?: { frequencyPenalty?: number; maxRetries?: number; maxTokens?: number; presencePenalty?: number; seed?: number; stopSequences?: string[]; temperature?: number; topK?: number; topP?: number; }; requireToolApproval?: boolean; returnScorerData?: boolean; runId?: string; savePerStep?: boolean; toolCallConcurrency?: number | { limit?: number; strategy?: "available" | "called"; }; toolChoice?: "none" | "auto" | "required" | { toolName: string; type: "tool"; }; tracingOptions?: { attributes?: {[key: string]: unknown; }; spanId?: string; traceId?: string; traceName?: string; }; } | object[]; description?: string; durable?: boolean | { cleanupTimeoutMs?: number; maxSteps?: number; }; favoriteCount?: number; id: string; inputProcessors?: { steps: ({ step: { config: {[key: string]: unknown; }; enabledPhases: ("processInput" | "processInputStep" | "processOutputStream" | "processOutputResult" | "processOutputStep" | "processToolResult")[]; id: string; providerId: string; }; type: "step"; } | { branches: ({ step: …; type: …; } | { branches: …; type: …; } | { conditions: …; type: …; })[][]; type: "parallel"; } | { conditions: object[]; type: "conditional"; })[]; } | object[]; instructions: string | ({ content: string; type: "text"; } | { id: string; type: "prompt_block_ref"; } | { content: string; rules?: { conditions: ({ field: …; operator: …; value?: …; } | { conditions: …; operator: …; })[]; operator: "AND" | "OR"; }; type: "prompt_block"; })[]; integrationTools?: {[key: string]: object; } | object[]; isFavorited?: boolean; mcpClients?: {[key: string]: object; } | object[]; memory?: { embedder?: string; embedderOptions?: {[key: string]: unknown; }; observationalMemory?: boolean | { model?: string; observation?: { blockAfter?: number; bufferActivation?: number; bufferTokens?: number | false; maxTokensPerBatch?: number; messageTokens?: number; model?: string; modelSettings?: {[key: string]: unknown; }; providerOptions?: {[key: string]: … | …; }; }; reflection?: { blockAfter?: number; bufferActivation?: number; model?: string; modelSettings?: {[key: string]: unknown; }; observationTokens?: number; providerOptions?: {[key: string]: … | …; }; }; scope?: "thread" | "resource"; shareTokenBudget?: boolean; }; options?: { generateTitle?: boolean | { emitEvent?: boolean; instructions?: string; minMessages?: number; model?: string; }; lastMessages?: number | false; messageHistory?: { atMaxRemoveTokens?: number; maxTokens: number; }; readOnly?: boolean; semanticRecall?: boolean | { indexName?: string; messageRange: number | { after: number; before: number; }; scope?: "thread" | "resource"; threshold?: number; topK: number; }; }; vector?: string | false; } | object[]; metadata?: {[key: string]: unknown; }; model: {[key: string]: unknown; name: string; provider: string; } | object[]; name: string; outputProcessors?: { steps: ({ step: { config: {[key: string]: unknown; }; enabledPhases: ("processInput" | "processInputStep" | "processOutputStream" | "processOutputResult" | "processOutputStep" | "processToolResult")[]; id: string; providerId: string; }; type: "step"; } | { branches: ({ step: …; type: …; } | { branches: …; type: …; } | { conditions: …; type: …; })[][]; type: "parallel"; } | { conditions: object[]; type: "conditional"; })[]; } | object[]; requestContextSchema?: {[key: string]: unknown; }; scorers?: {[key: string]: object; } | object[]; skills?: {[key: string]: object; } | object[]; status: string; toolProviders?: {[key: string]: object; } | object[]; tools?: {[key: string]: object; } | object[]; updatedAt: string; visibility?: "public" | "private"; workflows?: object[] | {[key: string]: object; }; workspace?: { type: "id"; workspaceId: string; } | { config: { autoSync?: boolean; description?: string; filesystem?: { config: {[key: string]: unknown; }; provider: string; }; mounts?: {[key: string]: object; }; name: string; operationTimeout?: number; sandbox?: { config: {[key: string]: unknown; }; provider: string; }; search?: { autoIndexPaths?: string[]; bm25?: boolean | { b?: number; k1?: number; }; embedderConfig?: {[key: string]: unknown; }; embedderModel?: string; embedderProvider?: string; searchIndexName?: string; vectorConfig?: {[key: string]: unknown; }; vectorProvider?: string; }; skills?: string[]; tools?: { enabled?: boolean; requireApproval?: boolean; tools?: {[key: string]: object; }; }; }; type: "inline"; } | { config: {[key: string]: unknown; }; provider: string; type: "provider"; } | object[]; }>

Promise containing the created stored agent

Inherited from

MastraClient.createStoredAgent

createStoredMCPClient()

createStoredMCPClient(params): Promise<{ activeVersionId?: string; authorId?: string; createdAt: string; description?: string; id: string; metadata?: {[key: string]: unknown; }; name: string; servers: {[key: string]: object; }; status: string; updatedAt: string; }>

Creates a new stored MCP client

Parameters

params

MCP client configuration

authorId?

string

Author identifier for multi-tenant filtering

description?

string

Description of the MCP client

id?

string

Unique identifier. If not provided, derived from name.

metadata?

{[key: string]: unknown; }

Additional metadata for the MCP client

name

string

Name of the MCP client

servers

{[key: string]: object; }

Map of server name to server configuration

Returns

Promise<{ activeVersionId?: string; authorId?: string; createdAt: string; description?: string; id: string; metadata?: {[key: string]: unknown; }; name: string; servers: {[key: string]: object; }; status: string; updatedAt: string; }>

Promise containing the created stored MCP client

Inherited from

MastraClient.createStoredMCPClient

createStoredPromptBlock()

createStoredPromptBlock(params): Promise<{ activeVersionId?: string; authorId?: string; content: string; createdAt: string; description?: string; hasDraft?: boolean; id: string; metadata?: {[key: string]: unknown; }; name: string; requestContextSchema?: {[key: string]: unknown; }; rules?: { conditions: ({ field: string; operator: Shared_Type_8; value?: unknown; } | { conditions: ({ field: string; operator: Shared_Type_8; value?: unknown; } | { conditions: …[]; operator: … | …; })[]; operator: "AND" | "OR"; })[]; operator: "AND" | "OR"; }; status: string; updatedAt: string; }>

Creates a new stored prompt block

Parameters

params

Prompt block configuration including name, content, rules, etc.

authorId?

string

Author identifier for multi-tenant filtering

content

string

Template content with {{variable}} interpolation

description?

string

Purpose description

id?

string

Unique identifier. If not provided, derived from name.

metadata?

{[key: string]: unknown; }

Additional metadata for the prompt block

name

string

Display name of the prompt block

requestContextSchema?

{[key: string]: unknown; }

JSON Schema defining available variables for {{variableName}} interpolation and conditions

rules?

{ conditions: ({ field: string; operator: InputShared_Type_31; value?: unknown; } | { conditions: ({ field: string; operator: InputShared_Type_31; value?: unknown; } | { conditions: object[]; operator: "AND" | "OR"; })[]; operator: "AND" | "OR"; })[]; operator: "AND" | "OR"; }

Rules for conditional inclusion

rules.conditions

({ field: string; operator: InputShared_Type_31; value?: unknown; } | { conditions: ({ field: string; operator: InputShared_Type_31; value?: unknown; } | { conditions: object[]; operator: "AND" | "OR"; })[]; operator: "AND" | "OR"; })[]

rules.operator

"AND" | "OR"

Returns

Promise<{ activeVersionId?: string; authorId?: string; content: string; createdAt: string; description?: string; hasDraft?: boolean; id: string; metadata?: {[key: string]: unknown; }; name: string; requestContextSchema?: {[key: string]: unknown; }; rules?: { conditions: ({ field: string; operator: Shared_Type_8; value?: unknown; } | { conditions: ({ field: string; operator: Shared_Type_8; value?: unknown; } | { conditions: …[]; operator: … | …; })[]; operator: "AND" | "OR"; })[]; operator: "AND" | "OR"; }; status: string; updatedAt: string; }>

Promise containing the created stored prompt block

Inherited from

MastraClient.createStoredPromptBlock

createStoredScorer()

createStoredScorer(params): Promise<{ activeVersionId?: string; authorId?: string; createdAt: string; defaultSampling?: { type: "none"; } | { rate: number; type: "ratio"; }; description?: string; id: string; instructions?: string; metadata?: {[key: string]: unknown; }; model?: {[key: string]: unknown; name: string; provider: string; }; name: string; presetConfig?: {[key: string]: unknown; }; scoreRange?: { max?: number; min?: number; }; status: string; type: Shared_Type_76; updatedAt: string; }>

Creates a new stored scorer definition

Parameters

params

Scorer definition configuration

authorId?

string

Author identifier for multi-tenant filtering

defaultSampling?

{ type: "none"; } | { rate: number; type: "ratio"; }

Default sampling configuration

description?

string

Description of the scorer

id?

string

Unique identifier. If not provided, derived from name.

instructions?

string

System instructions for the judge LLM (used when type is llm-judge)

metadata?

{[key: string]: unknown; }

Additional metadata for the scorer

model?

{[key: string]: unknown; name: string; provider: string; }

Model configuration for LLM judge

model.name

string

Model name (e.g., gpt-4o, claude-3-opus)

model.provider

string

Model provider (e.g., openai, anthropic)

name

string

Name of the scorer

presetConfig?

{[key: string]: unknown; }

Serializable config options for preset scorers

scoreRange?

{ max?: number; min?: number; }

Score range configuration (used when type is llm-judge)

scoreRange.max?

number

Maximum score value (default: 1)

scoreRange.min?

number

Minimum score value (default: 0)

type

InputShared_Type_90

Scorer type: llm-judge for custom, or a preset type name

Returns

Promise<{ activeVersionId?: string; authorId?: string; createdAt: string; defaultSampling?: { type: "none"; } | { rate: number; type: "ratio"; }; description?: string; id: string; instructions?: string; metadata?: {[key: string]: unknown; }; model?: {[key: string]: unknown; name: string; provider: string; }; name: string; presetConfig?: {[key: string]: unknown; }; scoreRange?: { max?: number; min?: number; }; status: string; type: Shared_Type_76; updatedAt: string; }>

Promise containing the created stored scorer definition

Inherited from

MastraClient.createStoredScorer

createStoredSkill()

createStoredSkill(params): Promise<{ activeVersionId?: string; assets?: string[]; authorId?: string; compatibility?: unknown; createdAt: string; description: string; favoriteCount?: number; files?: object[]; id: string; instructions: string; isFavorited?: boolean; license?: string; metadata?: {[key: string]: unknown; }; name: string; references?: string[]; scripts?: string[]; source?: { packagePath: string; type: "external"; } | { projectPath: string; type: "local"; } | { mastraPath: string; type: "managed"; }; status: string; updatedAt: string; visibility?: "public" | "private"; }>

Creates a new stored skill

Parameters

params

Skill configuration

assets?

string[]

List of asset file paths

authorId?

string

Author identifier for multi-tenant filtering

compatibility?

unknown

Compatibility requirements

description

string

Description of what the skill does and when to use it

files?

object[]

Full file tree structure for the skill

id?

string

Unique identifier. If not provided, derived from name.

instructions

string

Markdown instructions for the skill

license?

string

License identifier for the skill

metadata?

{[key: string]: unknown; }

Additional metadata for the skill

name

string

Name of the skill

references?

string[]

List of reference file paths

scripts?

string[]

List of script file paths

source?

{ packagePath: string; type: "external"; } | { projectPath: string; type: "local"; } | { mastraPath: string; type: "managed"; }

Source location of the skill

visibility?

"public" | "private"

Skill visibility: private (owner/admin only) or public (any reader)

Returns

Promise<{ activeVersionId?: string; assets?: string[]; authorId?: string; compatibility?: unknown; createdAt: string; description: string; favoriteCount?: number; files?: object[]; id: string; instructions: string; isFavorited?: boolean; license?: string; metadata?: {[key: string]: unknown; }; name: string; references?: string[]; scripts?: string[]; source?: { packagePath: string; type: "external"; } | { projectPath: string; type: "local"; } | { mastraPath: string; type: "managed"; }; status: string; updatedAt: string; visibility?: "public" | "private"; }>

Promise containing the created stored skill

Inherited from

MastraClient.createStoredSkill

declineToolCallStream()

declineToolCallStream(agentId, params): Promise<MastraStreamResponse>

Deny a suspended tool through the same native resume contract.

Parameters

agentId

string

params

reason?

string

requestContext?

MastraRequestContextSnapshot

runId

string

signal?

AbortSignal

threadId?

string

toolCallId

string

Returns

Promise<MastraStreamResponse>

defaultModel()

defaultModel(agentId?, signal?): Promise<string | null>

Fetch the humanized name of the static default model agentId falls back to when no model is pinned, from GET ${basePath}/default-model. Returns the server-humanized displayName (never a raw endpoint id), or null when the agent resolves its model dynamically at call time (or the agent id is unknown) - there’s nothing static to advertise. The picker uses this to label its default option on load, before the /models catalogue arrives. Defaults to the server’s default agent when agentId is omitted.

Parameters

agentId?

string

signal?

AbortSignal

Returns

Promise<string | null>

defaultModelDetails()

defaultModelDetails(agentId?, signal?): Promise<{ agentId: string; displayName: string | null; model: string | null; }>

Fetch the complete resolved default-model descriptor for an agent.

Parameters

agentId?

string

signal?

AbortSignal

Returns

Promise<{ agentId: string; displayName: string | null; model: string | null; }>

deleteDataset()

deleteDataset(datasetId, tenancy?): Promise<{ success: boolean; }>

Deletes a dataset. When tenancy fields are supplied, the server only deletes the dataset if it belongs to the given tenant (silent no-op otherwise).

Parameters

datasetId

string

tenancy?

GetDatasetsDatasetId_QueryParams

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteDataset

deleteDatasetExperiment()

deleteDatasetExperiment(datasetId, experimentId, tenancy?): Promise<{ success: boolean; }>

Deletes a dataset experiment and its results. Tenancy fields, when provided, scope the dataset lookup on the server side.

The server also attempts to delete the experiment’s observability traces, cascading to their spans and trace-linked signals. Stores without observability or trace deletion support leave the traces in place.

Parameters

datasetId

string

experimentId

string

tenancy?

GetDatasetsDatasetId_QueryParams

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteDatasetExperiment

deleteDatasetItem()

deleteDatasetItem(datasetId, itemId): Promise<{ success: boolean; }>

Deletes a dataset item

Parameters

datasetId

string

itemId

string

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteDatasetItem

deleteExperiment()

deleteExperiment(experimentId, options?): Promise<{ success: boolean; }>

Deletes an experiment and its results regardless of dataset association (including experiments orphaned by dataset deletion). When tenancy fields are supplied, the server only deletes the experiment if it belongs to the given tenant (silent no-op otherwise).

Parameters

experimentId

string

options?

GetDatasetsDatasetId_QueryParams

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteExperiment

deleteFeedback()

deleteFeedback(params): Promise<{ success: boolean; }>

Deletes feedback records by feedbackId, optionally scoped to a tenant.

Parameters

params

DeleteObservabilityFeedback_Body

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteFeedback

deleteMessages()

deleteMessages(threadId, messageIds, options?): Promise<void>

Delete selected persisted messages before regenerating a turn.

Parameters

threadId

string

messageIds

string[]

options?

agentId?

string

signal?

AbortSignal

Returns

Promise<void>

deleteSchedule()

deleteSchedule(scheduleId): Promise<PostAgentsAgentIdModel_Response>

Deletes a schedule.

Parameters

scheduleId

string

Returns

Promise<PostAgentsAgentIdModel_Response>

Inherited from

MastraClient.deleteSchedule

deleteScores()

deleteScores(params): Promise<{ success: boolean; }>

Deletes score records by scoreId, optionally scoped to a tenant.

Parameters

params

DeleteObservabilityScores_Body

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteScores

deleteThread()

deleteThread(threadId, opts): Promise<DeleteMemoryThreadsThreadId_Response>

Parameters

threadId

string

opts

{ agentId: string; networkId?: undefined; requestContext?: RequestContext<unknown> | Record<string, any>; } | { agentId?: undefined; networkId: string; requestContext?: RequestContext<unknown> | Record<string, any>; }

Returns

Promise<DeleteMemoryThreadsThreadId_Response>

Inherited from

MastraClient.deleteThread

deleteTraces()

deleteTraces(params): Promise<{ success: true; }>

Deletes traces by ID, cascading to all associated spans and trace-linked signal events (scores, feedback, metrics, logs). Signals without a trace ID are untouched. On ClickHouse-backed stores, reads may briefly return deleted rows until the delete is fully applied.

Parameters

params

PostObservabilityTracesDelete_Body

Returns

Promise<{ success: true; }>

Inherited from

MastraClient.deleteTraces

feedback()

feedback(input): Promise<{ assessmentId?: string; ok: boolean; }>

Log user feedback for a turn to POST ${basePath}/route/feedback. traceId is the tr-<hex> value the server sent on the stream response (via MLFLOW_TRACE_ID_HEADER) for that assistant message; value carries a thumbs (boolean) / rating, and/or comment carries freeform text. The server logs it as a HUMAN assessment on the trace, attributed to the signed-in user.

Resolves with { ok: false } (not a throw) when the assessment couldn’t be recorded yet - most often because the trace is still exporting to MLflow - so callers can prompt a retry. Throws only on a transport / HTTP-level failure.

Parameters

input

comment?

string = ...

name?

string = ...

traceId

string = ...

value?

string | number | boolean = ...

Returns

Promise<{ assessmentId?: string; ok: boolean; }>

finalizeExperiment()

finalizeExperiment(params): Promise<{ agentVersion?: string | null; comparisonId?: string | null; completedAt: string | null; createdAt: string; datasetId: string | null; datasetVersion: number | null; description?: string; experimentSetId?: string | null; failedCount: number; id: string; metadata?: {[key: string]: unknown; }; name?: string; provenance?: { metadata?: {[key: string]: unknown; }; source?: string; sourceId?: string; sourceVersion?: string; } | null; runnerAttestation?: { invocationId: string; runnerId: string; runnerVersion?: string; } | null; scorerIds?: string[] | null; skippedCount: number; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; targetId: string | null; targetType: "agent" | "workflow" | "scorer" | "processor" | null; totalItems: number; trialIndex?: number | null; updatedAt: string; variantId?: string | null; }>

Finalizes an external experiment. The server computes counts from persisted results. Idempotent.

Parameters

params

PostDatasetsDatasetIdExperimentsExperimentIdResults_PathParams

Returns

Promise<{ agentVersion?: string | null; comparisonId?: string | null; completedAt: string | null; createdAt: string; datasetId: string | null; datasetVersion: number | null; description?: string; experimentSetId?: string | null; failedCount: number; id: string; metadata?: {[key: string]: unknown; }; name?: string; provenance?: { metadata?: {[key: string]: unknown; }; source?: string; sourceId?: string; sourceVersion?: string; } | null; runnerAttestation?: { invocationId: string; runnerId: string; runnerVersion?: string; } | null; scorerIds?: string[] | null; skippedCount: number; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; targetId: string | null; targetType: "agent" | "workflow" | "scorer" | "processor" | null; totalItems: number; trialIndex?: number | null; updatedAt: string; variantId?: string | null; }>

Inherited from

MastraClient.finalizeExperiment

generateDatasetItems()

generateDatasetItems(params): Promise<{ items: object[]; }>

Generates synthetic dataset items using AI. Items are returned for review, not auto-saved.

Parameters

params

GenerateDatasetItemsParams

Returns

Promise<{ items: object[]; }>

Inherited from

MastraClient.generateDatasetItems

getA2A()

getA2A(agentId): A2A

Gets an A2A client for interacting with an agent via the A2A protocol

Parameters

agentId

string

ID of the agent to interact with

Returns

A2A

A2A client instance

Inherited from

MastraClient.getA2A

getA2AV1()

getA2AV1(agentId): A2AV1

Gets an A2A Protocol v1.0 client for an agent.

Parameters

agentId

string

ID of the agent to interact with

Returns

A2AV1

Inherited from

MastraClient.getA2AV1

getAgent()

getAgent(agentId, version?, routeOverrides?): Agent

Gets an agent instance by ID

Parameters

agentId

string

ID of the agent to retrieve

version?

AgentVersionIdentifier

Optional version selector for stored agent overrides

routeOverrides?

stream?

string

Returns

Agent

Agent instance

Inherited from

MastraClient.getAgent

getAgentBuilderAction()

getAgentBuilderAction(actionId): AgentBuilder

Gets an agent builder instance for executing agent-builder workflows

Parameters

actionId

string

Returns

AgentBuilder

AgentBuilder instance

Inherited from

MastraClient.getAgentBuilderAction

getAgentBuilderActions()

getAgentBuilderActions(): Promise<{[key: string]: object; }>

Gets all available agent builder actions

Returns

Promise<{[key: string]: object; }>

Promise containing map of action IDs to action details

Inherited from

MastraClient.getAgentBuilderActions

getAgentController()

getAgentController(controllerId): AgentController

Scopes to an agent controller hosted on the connected Mastra instance. Use getAgentController(id).session(resourceId) to create/resume a session, stream its events, and send messages.

Parameters

controllerId

string

The id the agent controller is registered under on Mastra

Returns

AgentController

Inherited from

MastraClient.getAgentController

getBackgroundTask()

getBackgroundTask(backgroundTaskId): Promise<{ agentId: string; args: {[key: string]: unknown; }; completedAt?: string; createdAt: string; error?: { message: string; stack?: string; }; id: string; maxRetries: number; resourceId?: string; result?: unknown; retryCount: number; runId: string; startedAt?: string; status: "suspended" | "running" | "pending" | "completed" | "failed" | "cancelled" | "timed_out"; suspendPayload?: unknown; threadId?: string; timeoutMs: number; toolCallId: string; toolName: string; }>

Gets a single background task by ID.

Parameters

backgroundTaskId

string

Returns

Promise<{ agentId: string; args: {[key: string]: unknown; }; completedAt?: string; createdAt: string; error?: { message: string; stack?: string; }; id: string; maxRetries: number; resourceId?: string; result?: unknown; retryCount: number; runId: string; startedAt?: string; status: "suspended" | "running" | "pending" | "completed" | "failed" | "cancelled" | "timed_out"; suspendPayload?: unknown; threadId?: string; timeoutMs: number; toolCallId: string; toolName: string; }>

Inherited from

MastraClient.getBackgroundTask

getBranch()

getBranch(params): Promise<{ spans: object[]; traceId: string; }>

Retrieves the subtree of spans rooted at a given span. The optional depth field bounds descendant levels below the anchor (0 = anchor only; omitted = full subtree).

Parameters

params

GetBranchArgs

Returns

Promise<{ spans: object[]; traceId: string; }>

Inherited from

MastraClient.getBranch

getBuilderAvailableModels()

getBuilderAvailableModels(): Promise<{ providers: object[]; }>

Retrieves the AI providers/models available under the active builder model policy. The server applies the EE allowlist, so the result can be rendered directly in the model picker.

Returns

Promise<{ providers: object[]; }>

Promise containing the policy-filtered providers/models

Inherited from

MastraClient.getBuilderAvailableModels

getBuilderRegistryPopular()

getBuilderRegistryPopular(registryId, params?): Promise<{ count: number; limit: number; offset: number; skills: object[]; }>

Fetch the popular skills feed from a builder skill registry. Requires stored-skills:read permission.

Parameters

registryId

string

params?

limit?

number

offset?

number

Returns

Promise<{ count: number; limit: number; offset: number; skills: object[]; }>

Inherited from

MastraClient.getBuilderRegistryPopular

getBuilderRegistryPreview()

getBuilderRegistryPreview(registryId, params): Promise<{ content: string; }>

Fetch the rendered preview content for a single registry skill. Requires stored-skills:read permission.

Parameters

registryId

string

params

owner

string

path

string

repo

string

Returns

Promise<{ content: string; }>

Inherited from

MastraClient.getBuilderRegistryPreview

getBuilderSettings()

getBuilderSettings(): Promise<{ configuration?: { agent?: {[key: string]: unknown; agents?: { allowed?: string[]; }; models?: { allowed?: (… | …)[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; }; tools?: { allowed?: string[]; }; workflows?: { allowed?: string[]; }; }; }; enabled: boolean; features?: { agent?: { agents?: boolean; avatarUpload?: boolean; browser?: boolean; favorites?: boolean; memory?: boolean; model?: boolean; scorers?: boolean; skills?: boolean; tools?: boolean; variables?: boolean; workflows?: boolean; }; }; modelPolicy?: { active: boolean; allowed?: ({ kind: "custom"; modelId?: string; provider: string; } | { modelId?: string; provider: string; })[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; pickerVisible?: boolean; }; modelPolicyWarnings?: string[]; picker?: { visibleAgents: string[] | null; visibleTools: string[] | null; visibleWorkflows: string[] | null; }; }>

Retrieves agent builder settings for UI gating. Returns feature flags and configuration set by admin.

Returns

Promise<{ configuration?: { agent?: {[key: string]: unknown; agents?: { allowed?: string[]; }; models?: { allowed?: (… | …)[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; }; tools?: { allowed?: string[]; }; workflows?: { allowed?: string[]; }; }; }; enabled: boolean; features?: { agent?: { agents?: boolean; avatarUpload?: boolean; browser?: boolean; favorites?: boolean; memory?: boolean; model?: boolean; scorers?: boolean; skills?: boolean; tools?: boolean; variables?: boolean; workflows?: boolean; }; }; modelPolicy?: { active: boolean; allowed?: ({ kind: "custom"; modelId?: string; provider: string; } | { modelId?: string; provider: string; })[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; pickerVisible?: boolean; }; modelPolicyWarnings?: string[]; picker?: { visibleAgents: string[] | null; visibleTools: string[] | null; visibleWorkflows: string[] | null; }; }>

Promise containing builder settings

Inherited from

MastraClient.getBuilderSettings

getDataset()

getDataset(datasetId, tenancy?): Promise<SerializedRouteResponse<"GET /datasets/:datasetId">>

Gets a single dataset by ID. Optionally scope the lookup to a specific tenant organization/project — the server returns 404 if the dataset does not belong to the given tenant.

Parameters

datasetId

string

tenancy?

GetDatasetsDatasetId_QueryParams

Returns

Promise<SerializedRouteResponse<"GET /datasets/:datasetId">>

Inherited from

MastraClient.getDataset

getDatasetExperiment()

getDatasetExperiment(datasetId, experimentId): Promise<SerializedRouteResponse<"GET /datasets/:datasetId/experiments/:experimentId">>

Gets a single dataset experiment by ID

Parameters

datasetId

string

experimentId

string

Returns

Promise<SerializedRouteResponse<"GET /datasets/:datasetId/experiments/:experimentId">>

Inherited from

MastraClient.getDatasetExperiment

getDatasetItem()

getDatasetItem(datasetId, itemId): Promise<{ createdAt: string; datasetId: string; datasetVersion: number; expectedTrajectory?: unknown; externalId?: string | null; groundTruth?: unknown; id: string; input: unknown; metadata?: {[key: string]: unknown; } | null; requestContext?: {[key: string]: unknown; } | null; scorerIds?: string[] | null; source?: { referenceId?: string; type: "csv" | "json" | "trace" | "llm" | "experiment-result" | "candidate-screener"; } | null; toolMocks?: object[] | null; unmockedToolPolicy?: "allow" | "deny" | null; updatedAt: string; }>

Gets a single dataset item by ID

Parameters

datasetId

string

itemId

string

Returns

Inherited from

MastraClient.getDatasetItem

getDatasetItemVersion()

getDatasetItemVersion(datasetId, itemId, datasetVersion): Promise<{ createdAt: string; datasetId: string; datasetVersion: number; expectedTrajectory?: unknown; externalId?: string | null; groundTruth?: unknown; id: string; input: unknown; metadata?: {[key: string]: unknown; } | null; requestContext?: {[key: string]: unknown; } | null; scorerIds?: string[] | null; source?: { referenceId?: string; type: "csv" | "json" | "trace" | "llm" | "experiment-result" | "candidate-screener"; } | null; toolMocks?: object[] | null; unmockedToolPolicy?: "allow" | "deny" | null; updatedAt: string; }>

Gets a specific version of a dataset item

Parameters

datasetId

string

itemId

string

datasetVersion

number

Returns

Inherited from

MastraClient.getDatasetItemVersion

getDynamicWorkflow()

getDynamicWorkflow(dynamicWorkflowId): DynamicWorkflow

Gets a dynamic workflow instance by ID for further operations (details, delete). To execute a dynamic workflow, use getWorkflow(id).createRun() like any other workflow.

Parameters

dynamicWorkflowId

string

ID of the dynamic workflow definition

Returns

DynamicWorkflow

DynamicWorkflow instance

Inherited from

MastraClient.getDynamicWorkflow

getEntityNames()

getEntityNames(params?): Promise<{ names: string[]; }>

Returns distinct entity names with optional type filtering.

Parameters

params?

GetObservabilityDiscoveryEntityNames_QueryParams

Returns

Promise<{ names: string[]; }>

Inherited from

MastraClient.getEntityNames

getEntityTypes()

getEntityTypes(): Promise<{ entityTypes: Shared_Type_58[]; }>

Returns distinct entity types from observability data.

Returns

Promise<{ entityTypes: Shared_Type_58[]; }>

Inherited from

MastraClient.getEntityTypes

getEnvironments()

getEnvironments(): Promise<{ environments: string[]; }>

Returns distinct environments from observability data.

Returns

Promise<{ environments: string[]; }>

Inherited from

MastraClient.getEnvironments

getExperimentReviewSummary()

getExperimentReviewSummary(): Promise<{ counts: object[]; }>

Gets review status counts aggregated per experiment

Returns

Promise<{ counts: object[]; }>

Inherited from

MastraClient.getExperimentReviewSummary

getFeedbackAggregate()

getFeedbackAggregate(params): Promise<{ changePercent?: number | null; previousValue?: number | null; value: number | null; }>

Returns an aggregated feedback value with optional period-over-period comparison.

Parameters

params

PostObservabilityFeedbackAggregate_Body

Returns

Promise<{ changePercent?: number | null; previousValue?: number | null; value: number | null; }>

Inherited from

MastraClient.getFeedbackAggregate

getFeedbackBreakdown()

getFeedbackBreakdown(params): Promise<{ groups: object[]; }>

Returns feedback values grouped by specified dimensions.

Parameters

params

PostObservabilityFeedbackBreakdown_Body

Returns

Promise<{ groups: object[]; }>

Inherited from

MastraClient.getFeedbackBreakdown

getFeedbackPercentiles()

getFeedbackPercentiles(params): Promise<{ series: object[]; }>

Returns percentile values for feedback bucketed by time interval.

Parameters

params

PostObservabilityFeedbackPercentiles_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getFeedbackPercentiles

getFeedbackTimeSeries()

getFeedbackTimeSeries(params): Promise<{ series: object[]; }>

Returns feedback values bucketed by time interval with optional grouping.

Parameters

params

PostObservabilityFeedbackTimeseries_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getFeedbackTimeSeries

getInfrastructureStatus()

getInfrastructureStatus(): Promise<{ browser: { availableProviders: string[]; config: object[]; env: string | null; provider: string | null; registered: boolean; type: string | null; }; channels: { providers: object[]; }; registries: { skillsSh: { enabled: boolean; }; }; workspace: { config: object[]; filesystemProvider: string | null; hasFilesystem: boolean; hasSandbox: boolean; name: string | null; registered: boolean; sandboxProvider: string | null; source: string | null; type: string | null; workspaceId: string | null; }; }>

Retrieves Agent Builder infrastructure configuration and resolution status. Requires infrastructure:read permission.

Returns

Promise<{ browser: { availableProviders: string[]; config: object[]; env: string | null; provider: string | null; registered: boolean; type: string | null; }; channels: { providers: object[]; }; registries: { skillsSh: { enabled: boolean; }; }; workspace: { config: object[]; filesystemProvider: string | null; hasFilesystem: boolean; hasSandbox: boolean; name: string | null; registered: boolean; sandboxProvider: string | null; source: string | null; type: string | null; workspaceId: string | null; }; }>

Promise containing infrastructure status

Inherited from

MastraClient.getInfrastructureStatus

getItemHistory()

getItemHistory(datasetId, itemId): Promise<{ history: object[]; }>

Lists versions for a dataset item

Parameters

datasetId

string

itemId

string

Returns

Promise<{ history: object[]; }>

Inherited from

MastraClient.getItemHistory

getLogForRun()

getLogForRun(params): Promise<{ hasMore: boolean; logs: object[]; page: number; perPage: number | false; total: number; }>

Gets logs for a specific run

Parameters

params

GetLogParams

Parameters containing run ID to retrieve

Returns

Promise<{ hasMore: boolean; logs: object[]; page: number; perPage: number | false; total: number; }>

Promise containing array of log messages

Inherited from

MastraClient.getLogForRun

getMcpServerDetails()

getMcpServerDetails(serverId, params?): Promise<GetMcpV0ServersId_Response>

Retrieves detailed information for a specific MCP server.

Parameters

serverId

string

The ID of the MCP server to retrieve.

params?

GetMcpV0ServersId_QueryParams

Optional parameters, e.g., specific version.

Returns

Promise<GetMcpV0ServersId_Response>

Promise containing the detailed MCP server information.

Inherited from

MastraClient.getMcpServerDetails

getMcpServerResources()

getMcpServerResources(serverId): Promise<GetMcpServerIdResources_Response>

Lists resources available on an MCP server.

Parameters

serverId

string

The ID of the MCP server.

Returns

Promise<GetMcpServerIdResources_Response>

Promise containing the list of resources.

Inherited from

MastraClient.getMcpServerResources

getMcpServers()

getMcpServers(params?): Promise<{ next: string | null; servers: object[]; total_count: number; }>

Retrieves a list of available MCP servers.

Parameters

params?

Optional parameters for pagination (page, perPage, or deprecated offset, limit).

limit?

number

Deprecated

Use perPage instead

offset?

number

Deprecated

Use page instead

page?

number

perPage?

number

Returns

Promise<{ next: string | null; servers: object[]; total_count: number; }>

Promise containing the list of MCP servers and pagination info.

Inherited from

MastraClient.getMcpServers

getMcpServerTool()

getMcpServerTool(serverId, toolId): MCPTool

Gets an MCPTool resource instance for a specific tool on an MCP server. This instance can then be used to fetch details or execute the tool.

Parameters

serverId

string

The ID of the MCP server.

toolId

string

The ID of the tool.

Returns

MCPTool

MCPTool instance.

Inherited from

MastraClient.getMcpServerTool

getMcpServerTools()

getMcpServerTools(serverId): Promise<{ tools: object[]; }>

Retrieves a list of tools for a specific MCP server.

Parameters

serverId

string

The ID of the MCP server.

Returns

Promise<{ tools: object[]; }>

Promise containing the list of tools.

Inherited from

MastraClient.getMcpServerTools

getMemoryConfig()

getMemoryConfig(params): Promise<{ config: { lastMessages?: number | false; messageHistory?: { atMaxRemoveTokens?: number; maxTokens: number; }; observationalMemory?: { enabled: boolean; messageTokens?: number | { max: number; min: number; }; observationModel?: string; observationModelRouting?: object[]; observationTokens?: number | { max: number; min: number; }; reflectionModel?: string; reflectionModelRouting?: object[]; scope?: "thread" | "resource"; shareTokenBudget?: boolean; }; semanticRecall?: unknown; workingMemory?: {[key: string]: unknown; enabled?: boolean; schema?: unknown; scope?: "thread" | "resource"; template?: string; version?: "stable" | "vnext"; }; } | null; memoryType?: "local" | "gateway"; }>

Retrieves memory config for a resource

Parameters

params

GetMemoryConfigParams

Parameters containing the resource ID and optional request context

Returns

Promise<{ config: { lastMessages?: number | false; messageHistory?: { atMaxRemoveTokens?: number; maxTokens: number; }; observationalMemory?: { enabled: boolean; messageTokens?: number | { max: number; min: number; }; observationModel?: string; observationModelRouting?: object[]; observationTokens?: number | { max: number; min: number; }; reflectionModel?: string; reflectionModelRouting?: object[]; scope?: "thread" | "resource"; shareTokenBudget?: boolean; }; semanticRecall?: unknown; workingMemory?: {[key: string]: unknown; enabled?: boolean; schema?: unknown; scope?: "thread" | "resource"; template?: string; version?: "stable" | "vnext"; }; } | null; memoryType?: "local" | "gateway"; }>

Promise containing memory configuration

Inherited from

MastraClient.getMemoryConfig

getMemoryStatus()

getMemoryStatus(agentId, requestContext?, opts?): Promise<{ memoryType?: "local" | "gateway"; observationalMemory?: { enabled: boolean; hasRecord?: boolean; isObserving?: boolean; isReflecting?: boolean; lastObservedAt?: string; observationTokenCount?: number; originType?: string; tokenCount?: number; }; result: boolean; }>

Gets the status of the memory system

Parameters

agentId

string

The agent ID

requestContext?

RequestContext<unknown> | Record<string, any>

opts?

Optional parameters including resourceId, threadId, and requestContext

resourceId?

string

threadId?

string

Returns

Promise<{ memoryType?: "local" | "gateway"; observationalMemory?: { enabled: boolean; hasRecord?: boolean; isObserving?: boolean; isReflecting?: boolean; lastObservedAt?: string; observationTokenCount?: number; originType?: string; tokenCount?: number; }; result: boolean; }>

Promise containing memory system status including observational memory info

Inherited from

MastraClient.getMemoryStatus

getMemoryThread()

getMemoryThread(threadId): MemoryThread

Gets a memory thread instance by ID

Parameters

threadId

ID of the memory thread to retrieve

agentId?

string

threadId

string

Returns

MemoryThread

MemoryThread instance

Inherited from

MastraClient.getMemoryThread

getMetricAggregate()

getMetricAggregate(params): Promise<{ changePercent?: number | null; costChangePercent?: number | null; costUnit?: string | null; estimatedCost?: number | null; previousEstimatedCost?: number | null; previousValue?: number | null; value: number | null; }>

Returns an aggregated metric value with optional period-over-period comparison.

Parameters

params

PostObservabilityMetricsAggregate_Body

Returns

Promise<{ changePercent?: number | null; costChangePercent?: number | null; costUnit?: string | null; estimatedCost?: number | null; previousEstimatedCost?: number | null; previousValue?: number | null; value: number | null; }>

Inherited from

MastraClient.getMetricAggregate

getMetricBreakdown()

getMetricBreakdown(params): Promise<{ groups: object[]; }>

Returns metric values grouped by specified dimensions.

Parameters

params

PostObservabilityMetricsBreakdown_Body

Returns

Promise<{ groups: object[]; }>

Inherited from

MastraClient.getMetricBreakdown

getMetricLabelKeys()

getMetricLabelKeys(params): Promise<{ keys: string[]; }>

Returns distinct label keys for a given metric.

Parameters

params

GetObservabilityDiscoveryMetricLabelKeys_QueryParams

Returns

Promise<{ keys: string[]; }>

Inherited from

MastraClient.getMetricLabelKeys

getMetricLabelValues()

getMetricLabelValues(params): Promise<{ values: string[]; }>

Returns distinct values for a given metric label key.

Parameters

params

GetObservabilityDiscoveryMetricLabelValues_QueryParams

Returns

Promise<{ values: string[]; }>

Inherited from

MastraClient.getMetricLabelValues

getMetricNames()

getMetricNames(params?): Promise<{ names: string[]; }>

Returns distinct metric names with optional prefix filtering.

Parameters

params?

GetObservabilityDiscoveryMetricNames_QueryParams

Returns

Promise<{ names: string[]; }>

Inherited from

MastraClient.getMetricNames

getMetricPercentiles()

getMetricPercentiles(params): Promise<{ series: object[]; }>

Returns percentile values for a metric bucketed by time interval.

Parameters

params

PostObservabilityMetricsPercentiles_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getMetricPercentiles

getMetricTimeSeries()

getMetricTimeSeries(params): Promise<{ series: object[]; }>

Returns metric values bucketed by time interval with optional grouping.

Parameters

params

PostObservabilityMetricsTimeseries_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getMetricTimeSeries

getObservabilityCapabilities()

getObservabilityCapabilities(): Promise<{ capabilities: { deltaPolling: boolean; discovery: { entityNames: boolean; entityTypes: boolean; environments: boolean; metrics: boolean; serviceNames: boolean; tags: boolean; }; feedback: boolean; logs: boolean; metrics: boolean; threadQuery: boolean; traceQuery: boolean; traceQueryDiscovery: boolean; traceQueryRootDuration: boolean; traceQueryTenantScope: boolean; }; observabilityStorageType: string | null; }>

Returns which optional observability APIs the configured observability storage supports.

Returns

Promise<{ capabilities: { deltaPolling: boolean; discovery: { entityNames: boolean; entityTypes: boolean; environments: boolean; metrics: boolean; serviceNames: boolean; tags: boolean; }; feedback: boolean; logs: boolean; metrics: boolean; threadQuery: boolean; traceQuery: boolean; traceQueryDiscovery: boolean; traceQueryRootDuration: boolean; traceQueryTenantScope: boolean; }; observabilityStorageType: string | null; }>

Inherited from

MastraClient.getObservabilityCapabilities

getObservationalMemory()

getObservationalMemory(params): Promise<{ history?: object[]; record: { activeObservations: string; bufferedObservationChunks?: object[]; bufferedObservations?: string; bufferedReflection?: string; config: {[key: string]: unknown; }; createdAt: string; generationCount: number; id: string; isObserving: boolean; isReflecting: boolean; lastObservedAt?: string; metadata?: {[key: string]: unknown; }; observationTokenCount: number; originType: "initial" | "observation" | "reflection"; pendingMessageTokens: number; resourceId: string; scope: "thread" | "resource"; threadId: string | null; totalTokensObserved: number; updatedAt: string; } | null; }>

Gets observational memory data for a resource or thread

Parameters

params

GetObservationalMemoryParams

Parameters containing agentId, resourceId, threadId, and optional request context

Returns

Promise<{ history?: object[]; record: { activeObservations: string; bufferedObservationChunks?: object[]; bufferedObservations?: string; bufferedReflection?: string; config: {[key: string]: unknown; }; createdAt: string; generationCount: number; id: string; isObserving: boolean; isReflecting: boolean; lastObservedAt?: string; metadata?: {[key: string]: unknown; }; observationTokenCount: number; originType: "initial" | "observation" | "reflection"; pendingMessageTokens: number; resourceId: string; scope: "thread" | "resource"; threadId: string | null; totalTokensObserved: number; updatedAt: string; } | null; }>

Promise containing the current OM record and history

Inherited from

MastraClient.getObservationalMemory

getPermissionPatterns()

getPermissionPatterns(): Promise<{ patterns: string[]; }>

Retrieves the authoritative list of valid permission-pattern strings. Used by Studio to validate route→permission literals and gate the sidebar.

Returns

Promise<{ patterns: string[]; }>

Promise containing the permission patterns

Inherited from

MastraClient.getPermissionPatterns

getProcessor()

getProcessor(processorId): Processor

Gets a processor instance by ID

Parameters

processorId

string

ID of the processor to retrieve

Returns

Processor

Processor instance

Inherited from

MastraClient.getProcessor

getProcessorProvider()

getProcessorProvider(providerId): ProcessorProvider

Gets a processor provider instance by ID for further operations

Parameters

providerId

string

ID of the processor provider

Returns

ProcessorProvider

ProcessorProvider instance

Inherited from

MastraClient.getProcessorProvider

getProcessorProviders()

getProcessorProviders(): Promise<GetProcessorProvidersResponse>

Lists all registered processor providers

Returns

Promise<GetProcessorProvidersResponse>

Promise containing list of processor provider info

Inherited from

MastraClient.getProcessorProviders

getSchedule()

getSchedule(scheduleId): Promise<ScheduleResponse>

Gets a single schedule by ID.

Parameters

scheduleId

string

Returns

Promise<ScheduleResponse>

Inherited from

MastraClient.getSchedule

getScoreAggregate()

getScoreAggregate(params): Promise<{ changePercent?: number | null; previousValue?: number | null; value: number | null; }>

Returns an aggregated score value with optional period-over-period comparison.

Parameters

params

PostObservabilityScoresAggregate_Body

Returns

Promise<{ changePercent?: number | null; previousValue?: number | null; value: number | null; }>

Inherited from

MastraClient.getScoreAggregate

getScoreBreakdown()

getScoreBreakdown(params): Promise<{ groups: object[]; }>

Returns score values grouped by specified dimensions.

Parameters

params

PostObservabilityScoresBreakdown_Body

Returns

Promise<{ groups: object[]; }>

Inherited from

MastraClient.getScoreBreakdown

getScorePercentiles()

getScorePercentiles(params): Promise<{ series: object[]; }>

Returns percentile values for scores bucketed by time interval.

Parameters

params

PostObservabilityScoresPercentiles_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getScorePercentiles

getScorer()

getScorer(scorerId): Promise<GetScorerResponse>

Retrieves a scorer by ID

Parameters

scorerId

string

ID of the scorer to retrieve

Returns

Promise<GetScorerResponse>

Promise containing the scorer

Inherited from

MastraClient.getScorer

getScoreTimeSeries()

getScoreTimeSeries(params): Promise<{ series: object[]; }>

Returns score values bucketed by time interval with optional grouping.

Parameters

params

PostObservabilityScoresTimeseries_Body

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getScoreTimeSeries

getServiceNames()

getServiceNames(): Promise<{ serviceNames: string[]; }>

Returns distinct service names from observability data.

Returns

Promise<{ serviceNames: string[]; }>

Inherited from

MastraClient.getServiceNames

getSpan()

getSpan(traceId, spanId): Promise<{ span: { attributes?: {[key: string]: unknown; } | null; createdAt: string; endedAt?: string | null; entityId?: string | null; entityName?: string | null; entityType?: Shared_Type_58 | null; entityVersionId?: string | null; environment?: string | null; error?: unknown; experimentId?: string | null; input?: unknown; isEvent: boolean; links?: unknown[] | null; metadata?: {[key: string]: unknown; } | null; name: string; organizationId?: string | null; output?: unknown; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: Shared_Type_58 | null; parentEntityVersionId?: string | null; parentSpanId?: string | null; requestContext?: {[key: string]: unknown; } | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: Shared_Type_58 | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: {[key: string]: unknown; } | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanId: string; spanType: Shared_Type_57; startedAt: string; tags?: string[] | null; threadId?: string | null; traceId: string; updatedAt: string | null; userId?: string | null; }; }>

Retrieves a single span with full details by trace ID and span ID.

Parameters

traceId

string

spanId

string

Returns

Promise<{ span: { attributes?: {[key: string]: unknown; } | null; createdAt: string; endedAt?: string | null; entityId?: string | null; entityName?: string | null; entityType?: Shared_Type_58 | null; entityVersionId?: string | null; environment?: string | null; error?: unknown; experimentId?: string | null; input?: unknown; isEvent: boolean; links?: unknown[] | null; metadata?: {[key: string]: unknown; } | null; name: string; organizationId?: string | null; output?: unknown; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: Shared_Type_58 | null; parentEntityVersionId?: string | null; parentSpanId?: string | null; requestContext?: {[key: string]: unknown; } | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: Shared_Type_58 | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: {[key: string]: unknown; } | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanId: string; spanType: Shared_Type_57; startedAt: string; tags?: string[] | null; threadId?: string | null; traceId: string; updatedAt: string | null; userId?: string | null; }; }>

Inherited from

MastraClient.getSpan

getStoredAgent()

getStoredAgent(storedAgentId): StoredAgent

Gets a stored agent instance by ID for further operations (details, update, delete)

Parameters

storedAgentId

string

ID of the stored agent to retrieve

Returns

StoredAgent

StoredAgent instance

Inherited from

MastraClient.getStoredAgent

getStoredMCPClient()

getStoredMCPClient(storedMCPClientId): StoredMCPClient

Gets a stored MCP client instance by ID for further operations (details, update, delete)

Parameters

storedMCPClientId

string

ID of the stored MCP client

Returns

StoredMCPClient

StoredMCPClient instance

Inherited from

MastraClient.getStoredMCPClient

getStoredPromptBlock()

getStoredPromptBlock(storedPromptBlockId): StoredPromptBlock

Gets a stored prompt block instance by ID for further operations (details, update, delete)

Parameters

storedPromptBlockId

string

ID of the stored prompt block to retrieve

Returns

StoredPromptBlock

StoredPromptBlock instance

Inherited from

MastraClient.getStoredPromptBlock

getStoredScorer()

getStoredScorer(storedScorerId): StoredScorer

Gets a stored scorer definition instance by ID for further operations (details, update, delete)

Parameters

storedScorerId

string

ID of the stored scorer definition

Returns

StoredScorer

StoredScorer instance

Inherited from

MastraClient.getStoredScorer

getStoredSkill()

getStoredSkill(storedSkillId): StoredSkill

Gets a stored skill instance by ID for further operations (details, update, delete)

Parameters

storedSkillId

string

ID of the stored skill

Returns

StoredSkill

StoredSkill instance

Inherited from

MastraClient.getStoredSkill

getStoredWorkspace()

getStoredWorkspace(id): Promise<{ activeVersionId?: string; authorId?: string; autoSync?: boolean; createdAt: string; description?: string; filesystem?: { config: {[key: string]: unknown; }; provider: string; }; id: string; metadata?: {[key: string]: unknown; }; mounts?: {[key: string]: object; }; name: string; operationTimeout?: number; sandbox?: { config: {[key: string]: unknown; }; provider: string; }; search?: { autoIndexPaths?: string[]; bm25?: boolean | { b?: number; k1?: number; }; embedderConfig?: {[key: string]: unknown; }; embedderModel?: string; embedderProvider?: string; searchIndexName?: string; vectorConfig?: {[key: string]: unknown; }; vectorProvider?: string; }; skills?: string[]; status: string; tools?: { enabled?: boolean; requireApproval?: boolean; tools?: {[key: string]: object; }; }; updatedAt: string; }>

Gets a specific stored workspace by ID

Parameters

id

string

The workspace ID

Returns

Promise<{ activeVersionId?: string; authorId?: string; autoSync?: boolean; createdAt: string; description?: string; filesystem?: { config: {[key: string]: unknown; }; provider: string; }; id: string; metadata?: {[key: string]: unknown; }; mounts?: {[key: string]: object; }; name: string; operationTimeout?: number; sandbox?: { config: {[key: string]: unknown; }; provider: string; }; search?: { autoIndexPaths?: string[]; bm25?: boolean | { b?: number; k1?: number; }; embedderConfig?: {[key: string]: unknown; }; embedderModel?: string; embedderProvider?: string; searchIndexName?: string; vectorConfig?: {[key: string]: unknown; }; vectorProvider?: string; }; skills?: string[]; status: string; tools?: { enabled?: boolean; requireApproval?: boolean; tools?: {[key: string]: object; }; }; updatedAt: string; }>

Promise containing the stored workspace

Inherited from

MastraClient.getStoredWorkspace

getSystemPackages()

getSystemPackages(): Promise<{ cmsEnabled: boolean; editorSource?: "code" | "db"; editorSourceCapabilities?: { canOpenChangeRequest: boolean; canSave: boolean; provider?: { displayName: string; id: string; }; source: "code" | "db"; storage: "filesystem" | "database" | "source-provider" | "unavailable"; unavailableReason?: string; }; isDev: boolean; liveKitConnectionRouteEnabled: boolean; observabilityEnabled: boolean; observabilityRuntimeStrategy?: "realtime" | "batch-with-updates" | "insert-only" | "event-sourced"; observabilityStorageCapabilities?: { deltaPolling: boolean; discovery: { entityNames: boolean; entityTypes: boolean; environments: boolean; metrics: boolean; serviceNames: boolean; tags: boolean; }; feedback: boolean; logs: boolean; metrics: boolean; threadQuery: boolean; traceQuery: boolean; traceQueryDiscovery: boolean; traceQueryRootDuration: boolean; traceQueryTenantScope: boolean; }; observabilityStorageType?: string; packages: object[]; storageType?: string; }>

Retrieves installed Mastra packages and their versions

Returns

Promise<{ cmsEnabled: boolean; editorSource?: "code" | "db"; editorSourceCapabilities?: { canOpenChangeRequest: boolean; canSave: boolean; provider?: { displayName: string; id: string; }; source: "code" | "db"; storage: "filesystem" | "database" | "source-provider" | "unavailable"; unavailableReason?: string; }; isDev: boolean; liveKitConnectionRouteEnabled: boolean; observabilityEnabled: boolean; observabilityRuntimeStrategy?: "realtime" | "batch-with-updates" | "insert-only" | "event-sourced"; observabilityStorageCapabilities?: { deltaPolling: boolean; discovery: { entityNames: boolean; entityTypes: boolean; environments: boolean; metrics: boolean; serviceNames: boolean; tags: boolean; }; feedback: boolean; logs: boolean; metrics: boolean; threadQuery: boolean; traceQuery: boolean; traceQueryDiscovery: boolean; traceQueryRootDuration: boolean; traceQueryTenantScope: boolean; }; observabilityStorageType?: string; packages: object[]; storageType?: string; }>

Promise containing the list of installed Mastra packages

Inherited from

MastraClient.getSystemPackages

getTags()

getTags(params?): Promise<{ tags: string[]; }>

Returns distinct tags with optional entity type filtering.

Parameters

params?

GetObservabilityDiscoveryEntityNames_QueryParams

Returns

Promise<{ tags: string[]; }>

Inherited from

MastraClient.getTags

getTool()

getTool(toolId): Tool

Gets a tool instance by ID

Parameters

toolId

string

ID of the tool to retrieve

Returns

Tool

Tool instance

Inherited from

MastraClient.getTool

getToolProvider()

getToolProvider(providerId): ToolProvider

Gets a tool provider instance by ID for further operations (listToolkits, listTools, getToolSchema)

Parameters

providerId

string

ID of the tool provider

Returns

ToolProvider

ToolProvider instance

Inherited from

MastraClient.getToolProvider

getTrace()

getTrace(traceId): Promise<{ spans: object[]; traceId: string; }>

Retrieves a specific trace by ID.

Parameters

traceId

string

Returns

Promise<{ spans: object[]; traceId: string; }>

Inherited from

MastraClient.getTrace

getTraceLight()

getTraceLight(traceId): Promise<{ spans: object[]; traceId: string; }>

Retrieves a lightweight trace by ID (timeline fields only, excludes heavy fields).

Parameters

traceId

string

Returns

Promise<{ spans: object[]; traceId: string; }>

Inherited from

MastraClient.getTraceLight

getTraceQueryFields()

getTraceQueryFields(params, options?): Promise<{ canonicalFields: object[]; observedFields: object[]; observedFieldsTruncated: boolean; }>

Returns canonical and observed fields available to the advanced trace-query grammar.

Parameters

params

PostObservabilityTracesQueryFields_Body

options?

signal?

AbortSignal

Returns

Promise<{ canonicalFields: object[]; observedFields: object[]; observedFieldsTruncated: boolean; }>

Inherited from

MastraClient.getTraceQueryFields

getTraceQueryValues()

getTraceQueryValues(params, options?): Promise<{ values: object[]; valuesTruncated: boolean; }>

Returns bounded string suggestions for one eligible trace-query field.

Parameters

params

PostObservabilityTracesQueryValues_Body

options?

signal?

AbortSignal

Returns

Promise<{ values: object[]; valuesTruncated: boolean; }>

Inherited from

MastraClient.getTraceQueryValues

getTraces()

getTraces(params): Promise<LegacyGetTracesResponse>

Retrieves paginated list of traces with optional filtering. This is the legacy API preserved for backward compatibility.

Parameters

params

LegacyTracesPaginatedArg

Parameters for pagination and filtering (legacy format)

Returns

Promise<LegacyGetTracesResponse>

Promise containing paginated traces and pagination info

Deprecated

Use listTraces instead for new features like ordering and more filters.

Inherited from

MastraClient.getTraces

getTraceTrajectory()

getTraceTrajectory(traceId): Promise<Trajectory>

Extracts a structured trajectory from a trace’s spans.

Parameters

traceId

string

Returns

Promise<Trajectory>

Inherited from

MastraClient.getTraceTrajectory

getVector()

getVector(vectorName): Vector

Gets a vector instance by name

Parameters

vectorName

string

Name of the vector to retrieve

Returns

Vector

Vector instance

Inherited from

MastraClient.getVector

getWorkflow()

getWorkflow(workflowId): Workflow

Gets a workflow instance by ID

Parameters

workflowId

string

ID of the workflow to retrieve

Returns

Workflow

Workflow instance

Inherited from

MastraClient.getWorkflow

getWorkflowBuilderSettings()

getWorkflowBuilderSettings(): Promise<{ enabled: boolean; modelPolicy?: { active: boolean; allowed?: ({ kind: "custom"; modelId?: string; provider: string; } | { modelId?: string; provider: string; })[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; pickerVisible?: boolean; }; }>

Retrieves workflow builder settings for UI gating.

Returns

Promise<{ enabled: boolean; modelPolicy?: { active: boolean; allowed?: ({ kind: "custom"; modelId?: string; provider: string; } | { modelId?: string; provider: string; })[]; default?: { kind: "custom"; modelId: string; provider: string; } | { modelId: string; provider: string; }; pickerVisible?: boolean; }; }>

Inherited from

MastraClient.getWorkflowBuilderSettings

getWorkingMemory()

getWorkingMemory(agentId): Promise<unknown>

Retrieves the working memory for a specific thread (optionally resource-scoped).

Parameters

agentId

ID of the agent.

agentId

string

requestContext?

RequestContext<unknown> | Record<string, any>

resourceId?

string

threadId

string

Returns

Promise<unknown>

Working memory for the specified thread or resource.

Inherited from

MastraClient.getWorkingMemory

getWorkspace()

getWorkspace(workspaceId): Workspace

Gets the workspace resource for filesystem, search, and skills operations

Parameters

workspaceId

string

Workspace ID to target

Returns

Workspace

Workspace instance

Inherited from

MastraClient.getWorkspace

history()

history(options): Promise<ListMemoryThreadMessagesResponse>

Fetch one page from Mastra’s native resource-scoped memory route.

Parameters

options

agentId?

string

page?

number

perPage?

number

signal?

AbortSignal

threadId

string

Returns

Promise<ListMemoryThreadMessagesResponse>

installBuilderRegistrySkill()

installBuilderRegistrySkill(registryId, body): Promise<{ filesWritten: number; name: string; storedSkillId: string; }>

Install a registry skill into the builder’s stored-skills DB. Returns 409 when a stored skill with the derived id already exists. Requires stored-skills:write permission.

Parameters

registryId

string

body

owner

string

GitHub repository owner

repo

string

GitHub repository name

skillName

string

Skill name from the registry

visibility?

"public" | "private"

Visibility for the new stored skill

Returns

Promise<{ filesWritten: number; name: string; storedSkillId: string; }>

Inherited from

MastraClient.installBuilderRegistrySkill

listAgentControllers()

listAgentControllers(): Promise<object[]>

Lists the agent controllers hosted on the connected Mastra instance.

Returns

Promise<object[]>

Promise containing one record per agent controller, carrying its id

Inherited from

MastraClient.listAgentControllers

listAgents()

listAgents(requestContext?, partial?): Promise<Record<string, GetAgentResponse>>

Retrieves all available agents

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

partial?

boolean

Returns

Promise<Record<string, GetAgentResponse>>

Promise containing map of agent IDs to agent details

Inherited from

MastraClient.listAgents

listAgentsModelProviders()

listAgentsModelProviders(): Promise<{ providers: object[]; }>

Returns

Promise<{ providers: object[]; }>

Inherited from

MastraClient.listAgentsModelProviders

listBackgroundTasks()

listBackgroundTasks(params?): Promise<{ tasks: object[]; total: number; }>

Lists background tasks with optional filtering and pagination.

Parameters

params?

agentId?

string

dateFilterBy?

"createdAt" | "suspendedAt" | "startedAt" | "completedAt"

fromDate?

Date

orderBy?

"createdAt" | "suspendedAt" | "startedAt" | "completedAt"

orderDirection?

"asc" | "desc"

page?

number

perPage?

number

resourceId?

string

runId?

string

status?

threadId?

string

toDate?

Date

toolCallId?

string

toolName?

string

Returns

Promise<{ tasks: object[]; total: number; }>

Inherited from

MastraClient.listBackgroundTasks

listBranches()

listBranches(params?): Promise<{ branches: object[]; delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Retrieves a paginated list of trace branches with optional filtering and sorting. Each row is a branch-anchor span (AGENT_RUN, WORKFLOW_RUN, TOOL_CALL, etc.) including ones nested under a different root entity. Pairs with getBranch to expand a single branch into its subtree.

Parameters

params?

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityBranches_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityBranches_QueryParams, "page" | "perPage">

Returns

Promise<{ branches: object[]; delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listBranches

listBuilderRegistries()

listBuilderRegistries(): Promise<{ registries: object[]; }>

Lists known skill registries surfaced by the Agent Builder config. Each entry reports whether the registry is enabled. Disabled or unknown registries return 404 from registry-scoped routes. Requires stored-skills:read permission.

Returns

Promise<{ registries: object[]; }>

Inherited from

MastraClient.listBuilderRegistries

listDatasetExperimentResults()

listDatasetExperimentResults(datasetId, experimentId, options?): Promise<ListDatasetExperimentResultsResponse>

Lists results for a dataset experiment. tags restricts the list to results that have all of the given tags.

Parameters

datasetId

string

experimentId

string

options?

GetDatasetsDatasetIdExperimentsExperimentIdResults_QueryParams

Returns

Promise<ListDatasetExperimentResultsResponse>

Inherited from

MastraClient.listDatasetExperimentResults

listDatasetExperiments()

listDatasetExperiments(datasetId, params?): Promise<{ experiments: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Lists experiments for a dataset

Parameters

datasetId

string

params?

GetExperiments_QueryParams

Returns

Promise<{ experiments: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listDatasetExperiments

listDatasetItems()

listDatasetItems(datasetId, params?): Promise<{ items: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Lists items in a dataset with optional pagination, search, and version filter

Parameters

datasetId

string

params?

GetDatasetsDatasetIdItems_QueryParams

Returns

Promise<{ items: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listDatasetItems

listDatasets()

listDatasets(params?): Promise<{ datasets: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Lists all datasets with optional pagination

Parameters

params?

orderBy?

{ direction: "ASC" | "DESC"; field: "name" | "createdAt" | "updatedAt"; }

orderBy.direction

"ASC" | "DESC"

orderBy.field

"name" | "createdAt" | "updatedAt"

page?

number

perPage?

number

targetIds?

string[]

Only return datasets attached to at least one of these target IDs

targetType?

"agent" | "workflow" | "scorer" | "processor"

Only return records attached to targets of this type

Returns

Promise<{ datasets: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listDatasets

listDatasetVersions()

listDatasetVersions(datasetId, pagination?): Promise<{ pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; versions: object[]; }>

Lists versions for a dataset

Parameters

datasetId

string

pagination?

GetScoresRunRunId_QueryParams

Returns

Promise<{ pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; versions: object[]; }>

Inherited from

MastraClient.listDatasetVersions

listDynamicWorkflows()

listDynamicWorkflows(params?): Promise<{ total: number; workflows: object[]; }>

Lists dynamic workflow definitions, optionally filtered by status or author

Parameters

params?

Optional filters: status (‘active’ | ‘archived’) and authorId

authorId?

string

Filter dynamic workflows by author identifier

status?

"archived" | "active"

Filter dynamic workflows by status (defaults to active when omitted by the handler)

Returns

Promise<{ total: number; workflows: object[]; }>

Promise containing the matching definitions and a total count

Inherited from

MastraClient.listDynamicWorkflows

listEmbedders()

listEmbedders(): Promise<{ embedders: object[]; }>

Lists all available embedding models

Returns

Promise<{ embedders: object[]; }>

Promise containing list of available embedders

Inherited from

MastraClient.listEmbedders

listExperiments()

listExperiments(params?): Promise<{ experiments: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Lists all experiments across all datasets

Parameters

params?

comparisonId?

string

experimentSetId?

string

orderBy?

{ direction: "ASC" | "DESC"; field: "status" | "createdAt"; }

orderBy.direction

"ASC" | "DESC"

orderBy.field

"status" | "createdAt"

page?

number

perPage?

number

targetId?

string

Only return experiments run against this target ID

targetType?

"agent" | "workflow" | "scorer" | "processor"

Only return records attached to targets of this type

trialIndex?

number

variantId?

string

Returns

Promise<{ experiments: object[]; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listExperiments

listFeedback()

listFeedback(params?): Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; feedback: object[]; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Retrieves a paginated list of feedback records.

Parameters

params?

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityFeedback_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityFeedback_QueryParams, "page" | "perPage">

Returns

Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; feedback: object[]; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listFeedback

listLogs()

listLogs(params): Promise<{ hasMore: boolean; logs: object[]; page: number; perPage: number | false; total: number; }>

Retrieves logs

Parameters

params

Parameters for filtering logs

filters?

string | string[]

fromDate?

Date

logLevel?

"error" | "debug" | "info" | "warn" | "silent"

page?

number

perPage?

number

toDate?

Date

transportId

string

Returns

Promise<{ hasMore: boolean; logs: object[]; page: number; perPage: number | false; total: number; }>

Promise containing array of log messages

Inherited from

MastraClient.listLogs

listLogsVNext()

listLogsVNext(params?): Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; logs: object[]; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Retrieves a paginated list of observability logs.

Parameters

params?

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityLogs_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityLogs_QueryParams, "page" | "perPage">

Returns

Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; logs: object[]; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; }>

Inherited from

MastraClient.listLogsVNext

listLogTransports()

listLogTransports(): Promise<GetLogsTransports_Response>

List of all log transports

Returns

Promise<GetLogsTransports_Response>

Promise containing list of log transports

Inherited from

MastraClient.listLogTransports

listMemoryThreads()

listMemoryThreads(params?): Promise<{ hasMore: boolean; page: number; perPage: number | false; threads: object[]; total: number; }>

Lists memory threads with optional filtering by resourceId and/or metadata

Parameters

params?

ListMemoryThreadsParams

Parameters containing optional filters, pagination options, and request context

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; threads: object[]; total: number; }>

Promise containing paginated array of memory threads with metadata

Inherited from

MastraClient.listMemoryThreads

listProcessors()

listProcessors(requestContext?): Promise<Record<string, { agentIds: string[]; configurations: object[]; description?: string; id: string; isWorkflow: boolean; name?: string; phases: ("input" | "inputStep" | "outputStream" | "outputResult" | "outputStep" | "toolResult")[]; }>>

Retrieves all available processors

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<Record<string, { agentIds: string[]; configurations: object[]; description?: string; id: string; isWorkflow: boolean; name?: string; phases: ("input" | "inputStep" | "outputStream" | "outputResult" | "outputStep" | "toolResult")[]; }>>

Promise containing map of processor IDs to processor details

Inherited from

MastraClient.listProcessors

listSchedules()

listSchedules(params?): Promise<{ schedules: ({ agentId: string; attributes?: {[key: string]: string | number | boolean | null | undefined; }; createdAt: number; cron: string; id: string; ifActive?: { attributes?: {[key: string]: string | number | boolean | null | undefined; }; behavior?: "deliver" | "persist" | "discard"; }; ifIdle?: { attributes?: {[key: string]: string | number | boolean | null | undefined; }; behavior?: "persist" | "discard" | "wake"; streamOptions?: { requestContext?: {[key: …]: …; }; }; }; lastFireAt?: number; lastRun?: undefined; lastRunId?: string; metadata?: {[key: string]: unknown; }; name?: string; nextFireAt: number; prompt: string; providerOptions?: {[key: string]: unknown; }; resourceId?: string; signalType?: "state" | "user" | "reactive" | "notification" | "user-message" | "system-reminder"; status: "active" | "paused"; tagName?: string; threadId?: string; timezone?: string; updatedAt: number; workflowId?: undefined; } | { agentId?: undefined; createdAt: number; cron: string; id: string; initialState?: unknown; inputData?: unknown; lastFireAt?: number; lastRun?: { completedAt?: number; durationMs?: number; error?: string; startedAt?: number; status: "success" | "suspended" | "running" | "pending" | "failed" | "paused" | "tripwire" | "waiting" | "canceled" | "bailed" | "skipped"; }; lastRunId?: string; metadata?: {[key: string]: unknown; }; nextFireAt: number; requestContext?: {[key: string]: unknown; }; resourceId?: string; status: "active" | "paused"; timezone?: string; updatedAt: number; workflowId: string; })[]; }>

Lists schedules — agent schedules and workflow schedules — with optional filtering by agentId, workflowId, or status. Agent schedules can additionally be filtered by threadId, resourceId, or name.

Parameters

params?

agentId?

string

name?

string

resourceId?

string

status?

"active" | "paused"

threadId?

string

workflowId?

string

Returns

Promise<{ schedules: ({ agentId: string; attributes?: {[key: string]: string | number | boolean | null | undefined; }; createdAt: number; cron: string; id: string; ifActive?: { attributes?: {[key: string]: string | number | boolean | null | undefined; }; behavior?: "deliver" | "persist" | "discard"; }; ifIdle?: { attributes?: {[key: string]: string | number | boolean | null | undefined; }; behavior?: "persist" | "discard" | "wake"; streamOptions?: { requestContext?: {[key: …]: …; }; }; }; lastFireAt?: number; lastRun?: undefined; lastRunId?: string; metadata?: {[key: string]: unknown; }; name?: string; nextFireAt: number; prompt: string; providerOptions?: {[key: string]: unknown; }; resourceId?: string; signalType?: "state" | "user" | "reactive" | "notification" | "user-message" | "system-reminder"; status: "active" | "paused"; tagName?: string; threadId?: string; timezone?: string; updatedAt: number; workflowId?: undefined; } | { agentId?: undefined; createdAt: number; cron: string; id: string; initialState?: unknown; inputData?: unknown; lastFireAt?: number; lastRun?: { completedAt?: number; durationMs?: number; error?: string; startedAt?: number; status: "success" | "suspended" | "running" | "pending" | "failed" | "paused" | "tripwire" | "waiting" | "canceled" | "bailed" | "skipped"; }; lastRunId?: string; metadata?: {[key: string]: unknown; }; nextFireAt: number; requestContext?: {[key: string]: unknown; }; resourceId?: string; status: "active" | "paused"; timezone?: string; updatedAt: number; workflowId: string; })[]; }>

Inherited from

MastraClient.listSchedules

listScheduleTriggers()

listScheduleTriggers(scheduleId, params?): Promise<{ triggers: object[]; }>

Lists trigger history for a schedule, ordered by actualFireAt descending.

Parameters

scheduleId

string

params?

fromActualFireAt?

number

limit?

number

toActualFireAt?

number

Returns

Promise<{ triggers: object[]; }>

Inherited from

MastraClient.listScheduleTriggers

listScorers()

listScorers(requestContext?): Promise<{[key: string]: object; }>

Retrieves all available scorers

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<{[key: string]: object; }>

Promise containing list of available scorers

Inherited from

MastraClient.listScorers

listScores()

listScores(params?): Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; scores: object[]; }>

Retrieves a paginated list of observability scores.

Parameters

params?

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityScores_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityScores_QueryParams, "page" | "perPage">

Returns

Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; scores: object[]; }>

Inherited from

MastraClient.listScores

listScoresByEntityId()

listScoresByEntityId(params): Promise<ListScoresResponse>

Retrieves scores by entity ID and type

Parameters

params

Parameters containing entity ID, type, and pagination options

entityId

string

Unique identifier for the entity

entityType

string

Type of the entity (AGENT or WORKFLOW)

page?

number

perPage?

number

Returns

Promise<ListScoresResponse>

Promise containing scores and pagination info

Inherited from

MastraClient.listScoresByEntityId

listScoresByRunId()

listScoresByRunId(params): Promise<ListScoresResponse>

Retrieves scores by run ID

Parameters

params

Parameters containing run ID and pagination options

page?

number

perPage?

number

runId

string

Unique identifier for the run

Returns

Promise<ListScoresResponse>

Promise containing scores and pagination info

Inherited from

MastraClient.listScoresByRunId

listScoresByScorerId()

listScoresByScorerId(params): Promise<ListScoresResponse>

Parameters

params

entityId?

string

entityType?

string

page?

number

perPage?

number

scorerId

string

Unique identifier for the scorer

Returns

Promise<ListScoresResponse>

Inherited from

MastraClient.listScoresByScorerId

listScoresBySpan()

listScoresBySpan(params): Promise<{ pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; scores: object[]; }>

Parameters

params

ListScoresBySpanParams

Returns

Promise<{ pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; scores: object[]; }>

Inherited from

MastraClient.listScoresBySpan

listStoredAgents()

listStoredAgents(params?): Promise<{ agents: object[]; hasMore: boolean; page: number; perPage: number | false; total: number; }>

Lists all stored agents with optional pagination

Parameters

params?

Optional pagination and ordering parameters

authorId?

string

Filter agents by author identifier

favoritedOnly?

string

When true, return only agents favorited by the caller (requires the favorites EE feature)

metadata?

{[key: string]: unknown; }

Filter agents by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

pinFavoritedFor?

string

When set, treat the given subject (user/role) as the favoriting principal for favoritedOnly instead of the caller

status?

"draft" | "published" | "archived"

Filter agents by status (defaults to published)

visibility?

"public"

Filter to only public agents

Returns

Promise<{ agents: object[]; hasMore: boolean; page: number; perPage: number | false; total: number; }>

Promise containing paginated list of stored agents

Inherited from

MastraClient.listStoredAgents

listStoredMCPClients()

listStoredMCPClients(params?): Promise<{ hasMore: boolean; mcpClients: object[]; page: number; perPage: number | false; total: number; }>

Lists all stored MCP clients with optional pagination

Parameters

params?

Optional pagination and ordering parameters

authorId?

string

Filter MCP clients by author identifier

metadata?

{[key: string]: unknown; }

Filter MCP clients by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

status?

"draft" | "published" | "archived"

Filter MCP clients by status (defaults to published)

Returns

Promise<{ hasMore: boolean; mcpClients: object[]; page: number; perPage: number | false; total: number; }>

Promise containing paginated list of stored MCP clients

Inherited from

MastraClient.listStoredMCPClients

listStoredPromptBlocks()

listStoredPromptBlocks(params?): Promise<{ hasMore: boolean; page: number; perPage: number | false; promptBlocks: object[]; total: number; }>

Lists all stored prompt blocks with optional pagination

Parameters

params?

Optional pagination and ordering parameters

authorId?

string

Filter prompt blocks by author identifier

metadata?

{[key: string]: unknown; }

Filter prompt blocks by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

status?

"draft" | "published" | "archived"

Filter prompt blocks by status. When omitted, returns all prompt blocks regardless of status

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; promptBlocks: object[]; total: number; }>

Promise containing paginated list of stored prompt blocks

Inherited from

MastraClient.listStoredPromptBlocks

listStoredScorers()

listStoredScorers(params?): Promise<{ hasMore: boolean; page: number; perPage: number | false; scorerDefinitions: object[]; total: number; }>

Lists all stored scorer definitions with optional pagination

Parameters

params?

Optional pagination and ordering parameters

authorId?

string

Filter scorers by author identifier

metadata?

{[key: string]: unknown; }

Filter scorers by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

status?

"draft" | "published" | "archived"

Filter scorers by status (defaults to published)

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; scorerDefinitions: object[]; total: number; }>

Promise containing paginated list of stored scorer definitions

Inherited from

MastraClient.listStoredScorers

listStoredSkills()

listStoredSkills(params?): Promise<{ hasMore: boolean; page: number; perPage: number | false; skills: object[]; total: number; }>

Lists all stored skills with optional pagination

Parameters

params?

Optional pagination and ordering parameters

authorId?

string

Filter skills by author identifier

favoritedOnly?

string

When true, return only skills favorited by the caller (requires the favorites EE feature)

metadata?

{[key: string]: unknown; }

Filter skills by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

pinFavoritedFor?

string

When set, treat the given subject (user/role) as the favoriting principal for favoritedOnly instead of the caller

status?

"draft" | "published" | "archived"

Filter skills by status

visibility?

"public"

Filter to only public skills

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; skills: object[]; total: number; }>

Promise containing paginated list of stored skills

Inherited from

MastraClient.listStoredSkills

listStoredWorkspaces()

listStoredWorkspaces(params?): Promise<{ hasMore: boolean; page: number; perPage: number | false; total: number; workspaces: object[]; }>

Lists stored workspace configurations from the database

Parameters

params?

Optional filter and pagination parameters

authorId?

string

Filter workspaces by author identifier

metadata?

{[key: string]: unknown; }

Filter workspaces by metadata key-value pairs

orderBy?

{ direction?: "ASC" | "DESC"; field?: "createdAt" | "updatedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"createdAt" | "updatedAt"

page?

number

perPage?

number

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; total: number; workspaces: object[]; }>

Promise containing paginated list of stored workspaces

Inherited from

MastraClient.listStoredWorkspaces

listThreadMessages()

listThreadMessages(threadId, opts?): Promise<ListMemoryThreadMessagesResponse>

Lists messages for a thread.

Parameters

threadId

string

ID of the thread

opts?

ListMemoryThreadMessagesParams

Optional parameters including agentId, networkId, and requestContext

When agentId is provided, uses the agent’s memory
When networkId is provided, uses the network endpoint
When neither is provided, uses storage directly

Returns

Promise<ListMemoryThreadMessagesResponse>

Promise containing the thread messages

Inherited from

MastraClient.listThreadMessages

listToolProviders()

listToolProviders(): Promise<{ providers: object[]; }>

Lists all registered tool providers

Returns

Promise<{ providers: object[]; }>

Promise containing list of tool provider info

Inherited from

MastraClient.listToolProviders

listTools()

listTools(requestContext?): Promise<Record<string, { description?: string; id: string; inputSchema?: string; outputSchema?: string; requestContextSchema?: string; requireApproval?: boolean; title?: string; }>>

Retrieves all available tools

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<Record<string, { description?: string; id: string; inputSchema?: string; outputSchema?: string; requestContextSchema?: string; requireApproval?: boolean; title?: string; }>>

Promise containing map of tool IDs to tool details

Inherited from

MastraClient.listTools

listTraces()

listTraces(params?): Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; spans: object[]; }>

Retrieves paginated list of traces with optional filtering and sorting. This is the new API with improved filtering options.

Parameters

params?

Parameters for pagination, filtering, and ordering

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityTraces_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityTraces_QueryParams, "page" | "perPage">

Returns

Promise containing paginated traces and pagination info

Inherited from

MastraClient.listTraces

listTracesLight()

listTracesLight(params?): Promise<{ delta?: { hasMore: boolean; limit: number; }; deltaCursor?: string; pagination?: { hasMore: boolean; page: number; perPage: number | false; total: number; }; spans: object[]; }>

Retrieves paginated list of traces carrying only the fields a trace list renders. Same contract as listTraces, but rows omit the attributes/input/output blobs and carry a short inputPreview instead.

Parameters

params?

Parameters for pagination, filtering, and ordering

after?

string

filters?

limit?

number

Maximum number of updates to return in one delta poll

mode?

"page" | "delta"

orderBy?

Pick<GetObservabilityTraces_QueryParams, "field" | "direction">

pagination?

Pick<GetObservabilityTraces_QueryParams, "page" | "perPage">

Returns

Promise containing paginated lightweight traces and pagination info

Inherited from

MastraClient.listTracesLight

listVectors()

listVectors(): Promise<{ vectors: object[]; }>

Lists all available vector stores

Returns

Promise<{ vectors: object[]; }>

Promise containing list of available vector stores

Inherited from

MastraClient.listVectors

listWorkflowRunCounts()

listWorkflowRunCounts(requestContext?): Promise<{[key: string]: object; }>

Retrieves per-workflow counts of running and suspended (awaiting resume) runs

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<{[key: string]: object; }>

Promise containing map of workflow IDs to run counts

Inherited from

MastraClient.listWorkflowRunCounts

listWorkflows()

listWorkflows(requestContext?, partial?): Promise<Record<string, GetWorkflowResponse>>

Retrieves all available workflows

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

partial?

boolean

Returns

Promise<Record<string, GetWorkflowResponse>>

Promise containing map of workflow IDs to workflow details

Inherited from

MastraClient.listWorkflows

listWorkspaces()

listWorkspaces(): Promise<{ workspaces: object[]; }>

Lists all workspaces from both Mastra instance and agents

Returns

Promise<{ workspaces: object[]; }>

Promise containing array of workspace items

Inherited from

MastraClient.listWorkspaces

mlflowExperiment()

mlflowExperiment(signal?): Promise<{ url: string | null; }>

Resolve the configured MLflow experiment for the active viewer. The server returns a URL only when that viewer has effective CAN_MANAGE; inability to determine access resolves to null.

Parameters

signal?

AbortSignal

Returns

Promise<{ url: string | null; }>

models()

models(signal?): Promise<object[]>

Fetch the cached Model Serving endpoint catalogue from GET ${basePath}/models. Returns every endpoint the plugin publishes (server-cached for ~5 minutes); callers filter to chat-capable models for a picker.

Parameters

signal?

AbortSignal

Returns

Promise<object[]>

observeAgentStream()

observeAgentStream(params): Promise<MastraStreamResponse>

Reconnect to the cached event stream for one background agent run.

Parameters

params

agentId

string

model?

string

runId

string

signal?

AbortSignal

threadId?

string

Returns

Promise<MastraStreamResponse>

pauseSchedule()

pauseSchedule(scheduleId): Promise<ScheduleResponse>

Pauses a schedule. The scheduler tick loop will skip paused schedules. Idempotent — pausing an already-paused schedule returns the current state unchanged. Pause status survives redeploys.

Parameters

scheduleId

string

Returns

Promise<ScheduleResponse>

Inherited from

MastraClient.pauseSchedule

purgeDatasetItem()

purgeDatasetItem(datasetId, itemId, tenancy?): Promise<{ success: boolean; }>

Permanently scrubs a dataset item’s data from all versions and linked experiment results

Parameters

datasetId

string

itemId

string

tenancy?

GetDatasetsDatasetId_QueryParams

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.purgeDatasetItem

queryTraces()

Call Signature

queryTraces(params): Promise<{ groups: object[]; page: { next: string | null; }; }>

Queries completed logical traces using recursive trace and related-record predicates. Grouped results remain supported but are deprecated. Use queryTraceThreads() to retrieve thread identities.

Parameters

params

QueryTracesGroupedInput

Returns

Promise<{ groups: object[]; page: { next: string | null; }; }>

Inherited from

MastraClient.queryTraces

Call Signature

queryTraces(params): Promise<{ delta: { hasMore: boolean; limit: number; }; deltaCursor: string; traces: object[]; }>

Queries completed logical traces using recursive trace and related-record predicates. Grouped results remain supported but are deprecated. Use queryTraceThreads() to retrieve thread identities.

Parameters

params

QueryTracesDeltaInput

Returns

Promise<{ delta: { hasMore: boolean; limit: number; }; deltaCursor: string; traces: object[]; }>

Inherited from

MastraClient.queryTraces

Call Signature

queryTraces(params): Promise<{ deltaCursor?: string; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; traces: object[]; }>

Queries completed logical traces using recursive trace and related-record predicates. Grouped results remain supported but are deprecated. Use queryTraceThreads() to retrieve thread identities.

Parameters

params

QueryTracesPaginatedInput

Returns

Promise<{ deltaCursor?: string; pagination: { hasMore: boolean; page: number; perPage: number | false; total: number; }; traces: object[]; }>

Inherited from

MastraClient.queryTraces

Call Signature

queryTraces(params): Promise<{ page: { next: string | null; }; traces: object[]; }>

Queries completed logical traces using recursive trace and related-record predicates. Grouped results remain supported but are deprecated. Use queryTraceThreads() to retrieve thread identities.

Parameters

params

QueryTracesKeysetInput

Returns

Promise<{ page: { next: string | null; }; traces: object[]; }>

Inherited from

MastraClient.queryTraces

Call Signature

queryTraces(params): Promise<TraceQueryResponse>

Queries completed logical traces using recursive trace and related-record predicates. Grouped results remain supported but are deprecated. Use queryTraceThreads() to retrieve thread identities.

Parameters

params

QueryTracesInput

Returns

Promise<TraceQueryResponse>

Inherited from

MastraClient.queryTraces

queryTraceThreads()

queryTraceThreads(params): Promise<{ page: { next: string | null; }; threads: object[]; }>

Queries thread identities using eligible-trace and cross-trace predicates.

Parameters

params

page?

{ after?: string | null; limit?: number; }

page.after?

string | null

page.limit?

number

traces

{ timeRange: { from: string; to: string; }; where?: unknown; }

traces.timeRange

{ from: string; to: string; }

traces.timeRange.from

string

traces.timeRange.to

string

traces.where?

unknown

where?

unknown

Returns

Promise<{ page: { next: string | null; }; threads: object[]; }>

Inherited from

MastraClient.queryTraceThreads

readMcpServerResource()

readMcpServerResource(serverId, uri): Promise<PostMcpServerIdResourcesRead_Response>

Reads the content of a resource from an MCP server. Used for fetching ui:// MCP App HTML content.

Parameters

serverId

string

The ID of the MCP server.

uri

string

The resource URI to read.

Returns

Promise<PostMcpServerIdResourcesRead_Response>

Promise containing the resource content.

Inherited from

MastraClient.readMcpServerResource

removeThread()

removeThread(threadId, options?): Promise<void>

Delete one native memory thread owned by the active resource.

Parameters

threadId

string

options?

agentId?

string

signal?

AbortSignal

Returns

Promise<void>

renameThread()

renameThread(threadId, title, options?): Promise<void>

Rename one native memory thread owned by the active resource.

Parameters

threadId

string

title

string

options?

agentId?

string

signal?

AbortSignal

Returns

Promise<void>

request()

request<T>(path, options?): Promise<T>

Makes an HTTP request to the API with retries and exponential backoff

Type Parameters

T

T

Parameters

path

string

The API endpoint path (without prefix, e.g., ‘/agents’)

options?

RequestOptions

Optional request configuration

Returns

Promise<T>

Promise containing the response data

Inherited from

MastraClient.request

resumeSchedule()

resumeSchedule(scheduleId): Promise<ScheduleResponse>

Resumes a paused schedule. Recomputes nextFireAt from ‘now’ so a long-paused schedule does not fire a backlog. Idempotent — resuming an already-active schedule returns the current state unchanged.

Parameters

scheduleId

string

Returns

Promise<ScheduleResponse>

Inherited from

MastraClient.resumeSchedule

runExperimentItem()

runExperimentItem(params): Promise<{ result: { attempt?: number; comment?: string | null; completedAt: string; createdAt: string; error: { code?: string; message: string; stack?: string; } | null; expectedTrajectory?: unknown; experimentId: string; groundTruth: unknown; id: string; input: unknown; itemDatasetVersion: number | null; itemId: string; metadata?: {[key: string]: unknown; } | null; output: unknown; retryCount: number; startedAt: string; status?: "needs-review" | "reviewed" | "complete" | null; tags?: string[] | null; toolMockReport?: { failure?: { args: unknown; code: "TOOL_MOCK_MISMATCH" | "TOOL_MOCK_EXHAUSTED" | "TOOL_MOCK_NOT_DECLARED"; toolName: string; }; liveCalls: object[]; served: object[]; unconsumed: object[]; } | null; traceId: string | null; }; scores: object[]; }>

Executes the experiment’s target against one dataset item server-side, runs the resolved scorers, and upserts the result row keyed by (experimentId, itemId, attempt) — safe to retry.

Parameters

params

RunExperimentItemParams

Returns

Promise<{ result: { attempt?: number; comment?: string | null; completedAt: string; createdAt: string; error: { code?: string; message: string; stack?: string; } | null; expectedTrajectory?: unknown; experimentId: string; groundTruth: unknown; id: string; input: unknown; itemDatasetVersion: number | null; itemId: string; metadata?: {[key: string]: unknown; } | null; output: unknown; retryCount: number; startedAt: string; status?: "needs-review" | "reviewed" | "complete" | null; tags?: string[] | null; toolMockReport?: { failure?: { args: unknown; code: "TOOL_MOCK_MISMATCH" | "TOOL_MOCK_EXHAUSTED" | "TOOL_MOCK_NOT_DECLARED"; toolName: string; }; liveCalls: object[]; served: object[]; unconsumed: object[]; } | null; traceId: string | null; }; scores: object[]; }>

Inherited from

MastraClient.runExperimentItem

runSchedule()

runSchedule(scheduleId): Promise<{ claimId: string; scheduledFireAt: number; scheduleId: string; }>

Fires a schedule manually, out-of-band from the cron schedule. Behaves like a scheduled fire but does not advance nextFireAt. The returned claimId is the trigger row’s runId — look it up via listScheduleTriggers(scheduleId).

Parameters

scheduleId

string

Returns

Promise<{ claimId: string; scheduledFireAt: number; scheduleId: string; }>

Inherited from

MastraClient.runSchedule

saveMessageToMemory()

saveMessageToMemory(params): Promise<SaveMessageToMemoryResponse>

Saves messages to memory

Parameters

params

SaveMessageToMemoryParams

Parameters containing messages to save and optional request context

Returns

Promise<SaveMessageToMemoryResponse>

Promise containing the saved messages

Inherited from

MastraClient.saveMessageToMemory

saveScore()

saveScore(params): Promise<SaveScoreResponse>

Saves a score

Parameters

params

SaveScoreParams

Parameters containing the score data to save

Returns

Promise<SaveScoreResponse>

Promise containing the saved score

Inherited from

MastraClient.saveScore

score()

score(params): Promise<{ message: string; status: string; traceCount: number; }>

Scores one or more traces using a specified scorer (fire-and-forget).

Parameters

params

PostObservabilityTracesScore_Body

Returns

Promise<{ message: string; status: string; traceCount: number; }>

Inherited from

MastraClient.score

searchBuilderRegistry()

searchBuilderRegistry(registryId, params): Promise<{ count: number; query: string; searchType: string; skills: object[]; }>

Search a builder skill registry. The registry must be enabled or the server returns 404. Requires stored-skills:read permission.

Parameters

registryId

string

params

limit?

number

q

string

Returns

Promise<{ count: number; query: string; searchType: string; skills: object[]; }>

Inherited from

MastraClient.searchBuilderRegistry

searchMemory()

searchMemory(__namedParameters): Promise<MemorySearchResponse>

Parameters

__namedParameters

agentId

string

memoryConfig?

any

requestContext?

RequestContext<unknown> | Record<string, any>

resourceId

string

searchQuery

string

threadId?

string

Returns

Promise<MemorySearchResponse>

Inherited from

MastraClient.searchMemory

statement()

statement(id, signal?): Promise<{ columns: string[]; rowCount: number; rows: Record<string, unknown>[]; truncated: boolean; } | undefined>

Resolve a [data:<id>] marker from GET ${basePath}/embed/data/:id. Returns the same coerced rows the get_statement tool produced for the model. A 404 resolves to undefined.

Parameters

id

string

signal?

AbortSignal

Returns

Promise<{ columns: string[]; rowCount: number; rows: Record<string, unknown>[]; truncated: boolean; } | undefined>

streamAgent()

streamAgent(params): Promise<MastraStreamResponse>

Open a native AI SDK UI stream for one Mastra conversation turn. Routing headers and cancellation remain isolated to this call.

Parameters

params

agentId

string

messages

UIMessage<unknown, UIDataTypes, UITools>[]

model?

string

reasoningEffort?

requestContext?

MastraRequestContextSnapshot

runId

string

signal?

AbortSignal

threadId?

string

Returns

Promise<MastraStreamResponse>

streamBackgroundTasks()

streamBackgroundTasks(params?): Promise<ReadableStream<unknown>>

Opens an SSE stream of background task events (completed/failed). Returns a Response that can be consumed as a ReadableStream.

Parameters

params?

agentId?

string

resourceId?

string

runId?

string

taskId?

string

threadId?

string

Returns

Promise<ReadableStream<unknown>>

Inherited from

MastraClient.streamBackgroundTasks

submitExperimentResult()

submitExperimentResult(params): Promise<{ attempt?: number; comment?: string | null; completedAt: string; createdAt: string; error: { code?: string; message: string; stack?: string; } | null; expectedTrajectory?: unknown; experimentId: string; groundTruth: unknown; id: string; input: unknown; itemDatasetVersion: number | null; itemId: string; metadata?: {[key: string]: unknown; } | null; output: unknown; retryCount: number; startedAt: string; status?: "needs-review" | "reviewed" | "complete" | null; tags?: string[] | null; toolMockReport?: { failure?: { args: unknown; code: "TOOL_MOCK_MISMATCH" | "TOOL_MOCK_EXHAUSTED" | "TOOL_MOCK_NOT_DECLARED"; toolName: string; }; liveCalls: object[]; served: object[]; unconsumed: object[]; } | null; traceId: string | null; }>

Submits (or re-submits) one item result for a target-less (ingestion) experiment. Upsert semantics on (experimentId, itemId, attempt) — safe to retry.

Parameters

params

SubmitExperimentResultParams

Returns

Promise<{ attempt?: number; comment?: string | null; completedAt: string; createdAt: string; error: { code?: string; message: string; stack?: string; } | null; expectedTrajectory?: unknown; experimentId: string; groundTruth: unknown; id: string; input: unknown; itemDatasetVersion: number | null; itemId: string; metadata?: {[key: string]: unknown; } | null; output: unknown; retryCount: number; startedAt: string; status?: "needs-review" | "reviewed" | "complete" | null; tags?: string[] | null; toolMockReport?: { failure?: { args: unknown; code: "TOOL_MOCK_MISMATCH" | "TOOL_MOCK_EXHAUSTED" | "TOOL_MOCK_NOT_DECLARED"; toolName: string; }; liveCalls: object[]; served: object[]; unconsumed: object[]; } | null; traceId: string | null; }>

Inherited from

MastraClient.submitExperimentResult

suggestions()

suggestions(agentId?, signal?): Promise<string[]>

Fetch the curated starter questions for agentId’s Genie space from GET ${basePath}/suggestions. Empty when the agent has no Genie space (or it defines none).

Parameters

agentId?

string

signal?

AbortSignal

Returns

Promise<string[]>

suspendedRuns()

suspendedRuns(agentId, threadId, signal?): Promise<{ runs: object[]; total: number; }>

Discover approval-gated runs persisted for a conversation.

Parameters

agentId

string

threadId

string

signal?

AbortSignal

Returns

Promise<{ runs: object[]; total: number; }>

threads()

threads(options?): Promise<{ hasMore: boolean; page: number; perPage: number | false; threads: object[]; total: number; }>

List the caller’s conversations through Mastra’s native memory API.

Parameters

options?

agentId?

string

page?

number

perPage?

number

signal?

AbortSignal

Returns

Promise<{ hasMore: boolean; page: number; perPage: number | false; threads: object[]; total: number; }>

triggerDatasetExperiment()

triggerDatasetExperiment(params): Promise<{ completedAt: string | null; datasetVersion?: number; experimentId: string; failedCount: number; results: object[]; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; totalItems: number; }>

Triggers a new dataset experiment

Parameters

params

TriggerDatasetExperimentParams

Returns

Inherited from

MastraClient.triggerDatasetExperiment

updateDataset()

updateDataset(params): Promise<{ createdAt: string; description?: string | null; groundTruthSchema?: {[key: string]: unknown; }; id: string; inputSchema?: {[key: string]: unknown; }; metadata?: {[key: string]: unknown; } | null; name: string; requestContextSchema?: {[key: string]: unknown; }; scorerIds?: string[] | null; tags?: string[] | null; targetIds?: string[] | null; targetType?: string | null; updatedAt: string; version: number; }>

Updates a dataset. Tenancy fields, when provided, scope the existence check on the server side so that a caller can only update datasets that belong to the given tenant.

Parameters

params

UpdateDatasetParams

Returns

Inherited from

MastraClient.updateDataset

updateDatasetExperiment()

updateDatasetExperiment(params): Promise<{ agentVersion?: string | null; comparisonId?: string | null; completedAt: string | null; createdAt: string; datasetId: string | null; datasetVersion: number | null; description?: string; experimentSetId?: string | null; failedCount: number; id: string; metadata?: {[key: string]: unknown; }; name?: string; provenance?: { metadata?: {[key: string]: unknown; }; source?: string; sourceId?: string; sourceVersion?: string; } | null; runnerAttestation?: { invocationId: string; runnerId: string; runnerVersion?: string; } | null; scorerIds?: string[] | null; skippedCount: number; startedAt: string | null; status: "running" | "pending" | "completed" | "failed"; succeededCount: number; targetId: string | null; targetType: "agent" | "workflow" | "scorer" | "processor" | null; totalItems: number; trialIndex?: number | null; updatedAt: string; variantId?: string | null; }>

Updates a dataset experiment’s name, description or metadata

Parameters

params

UpdateDatasetExperimentParams

Returns

Inherited from

MastraClient.updateDatasetExperiment

updateDatasetExperimentResult()

updateDatasetExperimentResult(params): Promise<{ attempt?: number; comment?: string | null; completedAt: string; createdAt: string; error: { code?: string; message: string; stack?: string; } | null; expectedTrajectory?: unknown; experimentId: string; groundTruth: unknown; id: string; input: unknown; itemDatasetVersion: number | null; itemId: string; metadata?: {[key: string]: unknown; } | null; output: unknown; retryCount: number; startedAt: string; status?: "needs-review" | "reviewed" | "complete" | null; tags?: string[] | null; toolMockReport?: { failure?: { args: unknown; code: "TOOL_MOCK_MISMATCH" | "TOOL_MOCK_EXHAUSTED" | "TOOL_MOCK_NOT_DECLARED"; toolName: string; }; liveCalls: object[]; served: object[]; unconsumed: object[]; } | null; traceId: string | null; }>

Updates an experiment result’s status, tags, and/or comment

Parameters

params

UpdateExperimentResultParams

Returns

Inherited from

MastraClient.updateDatasetExperimentResult

updateDatasetItem()

updateDatasetItem(params): Promise<{ createdAt: string; datasetId: string; datasetVersion: number; expectedTrajectory?: unknown; externalId?: string | null; groundTruth?: unknown; id: string; input: unknown; metadata?: {[key: string]: unknown; } | null; requestContext?: {[key: string]: unknown; } | null; scorerIds?: string[] | null; source?: { referenceId?: string; type: "csv" | "json" | "trace" | "llm" | "experiment-result" | "candidate-screener"; } | null; toolMocks?: object[] | null; unmockedToolPolicy?: "allow" | "deny" | null; updatedAt: string; }>

Updates a dataset item

Parameters

params

UpdateDatasetItemParams

Returns

Inherited from

MastraClient.updateDatasetItem

updateExperimentResult()

updateExperimentResult(params): Promise<DatasetExperimentResult>

Updates the status, tags, and/or comment on an experiment result

Parameters

params

UpdateExperimentResultParams

Returns

Promise<DatasetExperimentResult>

Inherited from

MastraClient.updateExperimentResult

updateFeedbackReviewStatus()

updateFeedbackReviewStatus(params): Promise<{ comment?: string | null; entityId?: string | null; entityName?: string | null; entityType?: Shared_Type_58 | null; entityVersionId?: string | null; environment?: string | null; executionSource?: string | null; experimentId?: string | null; feedbackId?: string | null; feedbackSource?: string | null; feedbackType: string; feedbackUserId?: string | null; metadata?: {[key: string]: unknown; } | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: Shared_Type_58 | null; parentEntityVersionId?: string | null; requestId?: string | null; resourceId?: string | null; reviewStatus: "needs-review" | "reviewed"; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: Shared_Type_58 | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: {[key: string]: unknown; } | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; sourceId?: string | null; spanId?: string | null; tags?: string[] | null; threadId?: string | null; timestamp: string; traceId?: string | null; userId?: string | null; value: string | number; }>

Updates a feedback record’s review workflow status.

Parameters

params

UpdateFeedbackReviewStatusArgs

Returns

Promise<{ comment?: string | null; entityId?: string | null; entityName?: string | null; entityType?: Shared_Type_58 | null; entityVersionId?: string | null; environment?: string | null; executionSource?: string | null; experimentId?: string | null; feedbackId?: string | null; feedbackSource?: string | null; feedbackType: string; feedbackUserId?: string | null; metadata?: {[key: string]: unknown; } | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: Shared_Type_58 | null; parentEntityVersionId?: string | null; requestId?: string | null; resourceId?: string | null; reviewStatus: "needs-review" | "reviewed"; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: Shared_Type_58 | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: {[key: string]: unknown; } | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; sourceId?: string | null; spanId?: string | null; tags?: string[] | null; threadId?: string | null; timestamp: string; traceId?: string | null; userId?: string | null; value: string | number; }>

Inherited from

MastraClient.updateFeedbackReviewStatus

updateSchedule()

updateSchedule(scheduleId, patch): Promise<ScheduleResponse>

Patches an existing schedule. Fields apply to the matching target type; agent-only fields on a workflow schedule are rejected. threadId / resourceId are immutable — to retarget, delete and recreate.

Parameters

scheduleId

string

patch

UpdateScheduleInput

Returns

Promise<ScheduleResponse>

Inherited from

MastraClient.updateSchedule

updateWorkingMemory()

updateWorkingMemory(agentId): Promise<unknown>

Updates the working memory for a specific thread (optionally resource-scoped).

Parameters

agentId

ID of the agent.

agentId

string

requestContext?

RequestContext<unknown> | Record<string, any>

resourceId?

string

threadId

string

workingMemory

string

Returns

Promise<unknown>

Inherited from

MastraClient.updateWorkingMemory

upsertDynamicWorkflow()

upsertDynamicWorkflow(params): Promise<{ dependencyIds?: string[]; id: string; ok: true; }>

Creates or replaces a dynamic workflow definition and live-registers it on the server. Optional dependencies lets helper workflows referenced by the root definition be saved in the same request; their ids are echoed back as dependencyIds.

Parameters

params

The workflow definition (id, schemas, graph) plus optional helper dependencies

dependencies?

object[]

Helper workflow definitions this workflow nests. Saved with it as one unit — the whole set is validated together, hydrated in derived dependency order, and rejected together, so a failed save never leaves orphaned helpers behind. Each helper becomes an ordinary dynamic workflow in its own right.

description?

string

graph

({ agentId: string; description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; outputSchema?: {[key: string]: unknown; }; type: "agent"; } | { description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; toolId: string; type: "tool"; } | { description?: string; id: string; mapConfig: string; metadata?: {[key: string]: unknown; }; type: "mapping"; } | { description?: string; id: string; type: "workflow"; workflowId: string; } | { description?: string; id?: string; metadata?: {[key: string]: unknown; }; steps: ({ agentId: string; description?: string; id: string; options?: { metadata?: {[key: …]: …; }; retries?: number; }; outputSchema?: {[key: string]: unknown; }; type: "agent"; } | { description?: string; id: string; options?: { metadata?: {[key: …]: …; }; retries?: number; }; toolId: string; type: "tool"; } | { description?: string; id: string; mapConfig: string; metadata?: {[key: string]: unknown; }; type: "mapping"; } | { description?: string; id: string; type: "workflow"; workflowId: string; })[]; type: "parallel"; } | { description?: string; id?: string; metadata?: {[key: string]: unknown; }; opts?: { concurrency: number; }; step: { agentId: string; description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; outputSchema?: {[key: string]: unknown; }; type: "agent"; } | { description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; toolId: string; type: "tool"; } | { description?: string; id: string; type: "workflow"; workflowId: string; }; type: "foreach"; } | { description?: string; duration: number; id: string; metadata?: {[key: string]: unknown; }; type: "sleep"; } | { date: string; description?: string; id: string; metadata?: {[key: string]: unknown; }; type: "sleepUntil"; } | { description?: string; id?: string; metadata?: {[key: string]: unknown; }; predicates: ({ left: { path: string; } | { literal: string | number | boolean | null; }; op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte"; right: { path: string; } | { literal: string | number | boolean | null; }; } | { op: "in" | "notIn"; set: (string | number | boolean | null)[]; value: { path: string; } | { literal: string | number | boolean | null; }; } | { op: "exists" | "notExists"; path: string; } | { op: "truthy" | "falsy"; value: { path: string; } | { literal: string | number | boolean | null; }; } | { args: ({ op: “eq” | “ne” | “lt” | “lte” | “gt” | “gte”; left: { path: string; } | { literal: string | number | boolean | null; }; right: { path: string; } | { literal: string | number | boolean | null; }; } | … 4 more … | { …; })[]; op: "and" | "or"; } | { arg: { op: “eq” | “ne” | “lt” | “lte” | “gt” | “gte”; left: { path: string; } | { literal: string | number | boolean | null; }; right: { path: string; } | { literal: string | number | boolean | null; }; } | … 4 more … | { …; }; op: "not"; })[]; steps: ({ agentId: string; description?: string; id: string; options?: { metadata?: {[key: …]: …; }; retries?: number; }; outputSchema?: {[key: string]: unknown; }; type: "agent"; } | { description?: string; id: string; options?: { metadata?: {[key: …]: …; }; retries?: number; }; toolId: string; type: "tool"; } | { description?: string; id: string; mapConfig: string; metadata?: {[key: string]: unknown; }; type: "mapping"; } | { description?: string; id: string; type: "workflow"; workflowId: string; })[]; type: "conditional"; } | { description?: string; id?: string; loopType: "dowhile" | "dountil"; metadata?: {[key: string]: unknown; }; predicate: { left: { path: string; } | { literal: string | number | boolean | null; }; op: "eq" | "ne" | "lt" | "lte" | "gt" | "gte"; right: { path: string; } | { literal: string | number | boolean | null; }; } | { op: "in" | "notIn"; set: (string | number | boolean | null)[]; value: { path: string; } | { literal: string | number | boolean | null; }; } | { op: "exists" | "notExists"; path: string; } | { op: "truthy" | "falsy"; value: { path: string; } | { literal: string | number | boolean | null; }; } | { args: { op: “eq” | “ne” | “lt” | “lte” | “gt” | “gte”; left: { path: string; } | { literal: string | number | boolean | null; }; right: { path: string; } | { literal: string | number | boolean | null; }; } | … 4 more … | { …; }[]; op: "and" | "or"; } | { arg: { op: “eq” | “ne” | “lt” | “lte” | “gt” | “gte”; left: { path: string; } | { literal: string | number | boolean | null; }; right: { path: string; } | { literal: string | number | boolean | null; }; } | … 4 more … | { …; }; op: "not"; }; step: { agentId: string; description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; outputSchema?: {[key: string]: unknown; }; type: "agent"; } | { description?: string; id: string; options?: { metadata?: {[key: string]: unknown; }; retries?: number; }; toolId: string; type: "tool"; } | { description?: string; id: string; mapConfig: string; metadata?: {[key: string]: unknown; }; type: "mapping"; } | { description?: string; id: string; type: "workflow"; workflowId: string; }; type: "loop"; })[]

Static workflow graph — ordered array of serialized step entries with all refs as ids.

id

string

Workflow id — kebab-case, descriptive

inputSchema

{[key: string]: unknown; }

JSON Schema (Draft 2020-12) for the workflow input

metadata?

{[key: string]: unknown; }

outputSchema

{[key: string]: unknown; }

JSON Schema (Draft 2020-12) for the workflow output

requestContextSchema?

{[key: string]: unknown; }

stateSchema?

{[key: string]: unknown; }

Returns

Promise<{ dependencyIds?: string[]; id: string; ok: true; }>

Promise containing the persisted definition and any dependency ids

Inherited from

MastraClient.upsertDynamicWorkflow