Class: MastraPluginClient

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

Conversation streaming via the inherited getAgent(id).stream() (the standard Mastra agent route).
Thread history (history / clearHistory), the conversation list (threads / removeThread / renameThread), 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[] = ...

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

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

addDatasetItem()

addDatasetItem(params): Promise<DatasetItem>

Adds an item to a dataset

Parameters

params

AddDatasetItemParams

Returns

Promise<DatasetItem>

Inherited from

MastraClient.addDatasetItem

approveToolCallStream()

approveToolCallStream(agentId, params): Promise<MastraStreamResponse>

Resume a suspended requireApproval tool via approve-tool-call. Reads SSE directly instead of agent.approveToolCall() so the stock client’s internal processChatResponse_vNext tee does not throw when the resume stream emits tool-result without a new tool-call.

Parameters

agentId

string

params

runId

string

signal?

AbortSignal

threadId?

string

toolCallId

string

Returns

Promise<MastraStreamResponse>

awaitBufferStatus()

awaitBufferStatus(params): Promise<{ record: { activeObservations: string; 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; 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: DatasetItem[]; }>

Batch inserts items to a dataset

Parameters

params

BatchInsertDatasetItemsParams

Returns

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

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<{ agentId: string; cleared: number; ok: true; threadId: string; }>

Wipe a thread’s history (DELETE ${basePath}/route/history). threadId targets a specific conversation via the thread-selection header (so it doesn’t depend on shared client state); omit it to clear the per-session cookie thread. The session cookie that anchors the thread id is preserved - only the messages go away. Idempotent: a fresh thread reports cleared: 0 without erroring.

Parameters

options?

agentId?

string

signal?

AbortSignal

threadId?

string

Returns

Promise<{ agentId: string; cleared: number; ok: true; threadId: string; }>

clusterFailures()

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

Cluster experiment failures using AI to identify common failure patterns.

Parameters

params

availableTags?

string[]

items

object[]

modelId

string

prompt?

string

Returns

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

Inherited from

MastraClient.clusterFailures

compareExperiments()

compareExperiments(params): Promise<CompareExperimentsResponse>

Compares two dataset experiments for regression detection

Parameters

params

CompareExperimentsParams

Returns

Promise<CompareExperimentsResponse>

Inherited from

MastraClient.compareExperiments

createDataset()

createDataset(params): Promise<DatasetRecord>

Creates a new dataset

Parameters

params

CreateDatasetParams

Returns

Promise<DatasetRecord>

Inherited from

MastraClient.createDataset

createFeedback()

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

Creates a single feedback record in the observability store.

Parameters

params

feedback

{ comment?: string | null; entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | 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?: Record<string, unknown> | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; sourceId?: string | null; spanId?: string | null; tags?: string[] | null; threadId?: string | null; traceId?: string | null; userId?: string | null; value: string | number; }

feedback.comment?

string | null

feedback.entityId?

string | null

feedback.entityName?

string | null

feedback.entityType?

feedback.entityVersionId?

string | null

feedback.environment?

string | null

feedback.executionSource?

string | null

feedback.experimentId?

string | null

feedback.feedbackId?

string | null

feedback.feedbackSource?

string | null

feedback.feedbackType

string

feedback.feedbackUserId?

string | null

feedback.metadata?

Record<string, unknown> | null

feedback.organizationId?

string | null

feedback.parentEntityId?

string | null

feedback.parentEntityName?

string | null

feedback.parentEntityType?

feedback.parentEntityVersionId?

string | null

feedback.requestId?

string | null

feedback.resourceId?

string | null

feedback.rootEntityId?

string | null

feedback.rootEntityName?

string | null

feedback.rootEntityType?

feedback.rootEntityVersionId?

string | null

feedback.runId?

string | null

feedback.scope?

Record<string, unknown> | null

feedback.serviceName?

string | null

feedback.sessionId?

string | null

feedback.source?

string | null

feedback.sourceId?

string | null

feedback.spanId?

string | null

feedback.tags?

string[] | null

feedback.threadId?

string | null

feedback.traceId?

string | null

feedback.userId?

string | null

feedback.value

string | number

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

createScore()

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

Creates a single score record in the observability store.

Parameters

params

score

{ entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; entityVersionId?: string | null; environment?: string | null; executionSource?: string | null; experimentId?: string | null; metadata?: Record<string, unknown> | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; reason?: string | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; score: number; scoreId?: string | null; scorerId: string; scorerName?: string | null; scorerVersion?: string | null; scoreSource?: string | null; scoreTraceId?: string | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanId?: string | null; tags?: string[] | null; threadId?: string | null; traceId?: string | null; userId?: string | null; }

score.entityId?

string | null

score.entityName?

string | null

score.entityType?

score.entityVersionId?

string | null

score.environment?

string | null

score.executionSource?

string | null

score.experimentId?

string | null

score.metadata?

Record<string, unknown> | null

score.organizationId?

string | null

score.parentEntityId?

string | null

score.parentEntityName?

string | null

score.parentEntityType?

score.parentEntityVersionId?

string | null

score.reason?

string | null

score.requestId?

string | null

score.resourceId?

string | null

score.rootEntityId?

string | null

score.rootEntityName?

string | null

score.rootEntityType?

score.rootEntityVersionId?

string | null

score.runId?

string | null

score.scope?

Record<string, unknown> | null

score.score

number

score.scoreId?

string | null

score.scorerId

string

score.scorerName?

string | null

score.scorerVersion?

string | null

score.scoreSource?

string | null

score.scoreTraceId?

string | null

score.serviceName?

string | null

score.sessionId?

string | null

score.source?

string | null

score.spanId?

string | null

score.tags?

string[] | null

score.threadId?

string | null

score.traceId?

string | null

score.userId?

string | null

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.createScore

createStoredAgent()

createStoredAgent(params): Promise<StoredAgentResponse>

Creates a new stored agent

Parameters

params

CreateStoredAgentParams

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

Returns

Promise<StoredAgentResponse>

Promise containing the created stored agent

Inherited from

MastraClient.createStoredAgent

createStoredMCPClient()

createStoredMCPClient(params): Promise<StoredMCPClientResponse>

Creates a new stored MCP client

Parameters

params

CreateStoredMCPClientParams

MCP client configuration

Returns

Promise<StoredMCPClientResponse>

Promise containing the created stored MCP client

Inherited from

MastraClient.createStoredMCPClient

createStoredPromptBlock()

createStoredPromptBlock(params): Promise<StoredPromptBlockResponse>

Creates a new stored prompt block

Parameters

params

CreateStoredPromptBlockParams

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

Returns

Promise<StoredPromptBlockResponse>

Promise containing the created stored prompt block

Inherited from

MastraClient.createStoredPromptBlock

createStoredScorer()

createStoredScorer(params): Promise<StoredScorerResponse>

Creates a new stored scorer definition

Parameters

params

CreateStoredScorerParams

Scorer definition configuration

Returns

Promise<StoredScorerResponse>

Promise containing the created stored scorer definition

Inherited from

MastraClient.createStoredScorer

createStoredSkill()

createStoredSkill(params): Promise<StoredSkillResponse>

Creates a new stored skill

Parameters

params

CreateStoredSkillParams

Skill configuration

Returns

Promise<StoredSkillResponse>

Promise containing the created stored skill

Inherited from

MastraClient.createStoredSkill

declineToolCallStream()

declineToolCallStream(agentId, params): Promise<MastraStreamResponse>

Deny a suspended requireApproval tool via decline-tool-call. Same direct SSE reader as approveToolCallStream.

Parameters

agentId

string

params

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>

deleteDataset()

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

Deletes a dataset

Parameters

datasetId

string

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteDataset

deleteDatasetItem()

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

Deletes a dataset item

Parameters

datasetId

string

itemId

string

Returns

Promise<{ success: boolean; }>

Inherited from

MastraClient.deleteDatasetItem

deleteThread()

deleteThread(threadId, opts): Promise<{ message: string; success: boolean; }>

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<{ message: string; success: boolean; }>

Inherited from

MastraClient.deleteThread

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; }>

generateDatasetItems()

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

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

Parameters

params

GenerateDatasetItemsParams

Returns

Promise<{ items: GeneratedItem[]; }>

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

getAgent()

getAgent(agentId, version?): 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

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<Record<string, WorkflowInfo>>

Gets all available agent builder actions

Returns

Promise<Record<string, WorkflowInfo>>

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: "running" | "pending" | "completed" | "failed" | "suspended" | "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: "running" | "pending" | "completed" | "failed" | "suspended" | "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

depth?

unknown

spanId

string

traceId

string

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<BuilderRegistryPopularResponse>

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<BuilderRegistryPopularResponse>

Inherited from

MastraClient.getBuilderRegistryPopular

getBuilderRegistryPreview()

getBuilderRegistryPreview(registryId, params): Promise<BuilderRegistryPreviewResponse>

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<BuilderRegistryPreviewResponse>

Inherited from

MastraClient.getBuilderRegistryPreview

getBuilderSettings()

getBuilderSettings(): Promise<BuilderSettingsResponse>

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

Returns

Promise<BuilderSettingsResponse>

Promise containing builder settings

Inherited from

MastraClient.getBuilderSettings

getDataset()

getDataset(datasetId): Promise<DatasetRecord>

Gets a single dataset by ID

Parameters

datasetId

string

Returns

Promise<DatasetRecord>

Inherited from

MastraClient.getDataset

getDatasetExperiment()

getDatasetExperiment(datasetId, experimentId): Promise<DatasetExperiment>

Gets a single dataset experiment by ID

Parameters

datasetId

string

experimentId

string

Returns

Promise<DatasetExperiment>

Inherited from

MastraClient.getDatasetExperiment

getDatasetItem()

getDatasetItem(datasetId, itemId): Promise<DatasetItem>

Gets a single dataset item by ID

Parameters

datasetId

string

itemId

string

Returns

Promise<DatasetItem>

Inherited from

MastraClient.getDatasetItem

getDatasetItemVersion()

getDatasetItemVersion(datasetId, itemId, datasetVersion): Promise<DatasetItemVersionResponse>

Gets a specific version of a dataset item

Parameters

datasetId

string

itemId

string

datasetVersion

number

Returns

Promise<DatasetItemVersionResponse>

Inherited from

MastraClient.getDatasetItemVersion

getEntityNames()

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

Returns distinct entity names with optional type filtering.

Parameters

params?

entityType?

Returns

Promise<{ names: string[]; }>

Inherited from

MastraClient.getEntityNames

getEntityTypes()

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

Returns distinct entity types from observability data.

Returns

Promise<{ entityTypes: EntityType[]; }>

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: ExperimentReviewCounts[]; }>

Gets review status counts aggregated per experiment

Returns

Promise<{ counts: ExperimentReviewCounts[]; }>

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

comparePeriod?

"previous_period" | "previous_day" | "previous_week"

feedbackSource?

string

feedbackType

string

filters?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; feedbackSource?: string; feedbackType?: string | string[]; feedbackUserId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.feedbackSource?

string

filters.feedbackType?

string | string[]

filters.feedbackUserId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

feedbackSource?

string

feedbackType

string

filters?

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.feedbackSource?

string

filters.feedbackType?

string | string[]

filters.feedbackUserId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy

string[]

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

feedbackSource?

string

feedbackType

string

filters?

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.feedbackSource?

string

filters.feedbackType?

string | string[]

filters.feedbackUserId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

interval

"1m" | "5m" | "15m" | "1h" | "1d"

percentiles

number[]

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

feedbackSource?

string

feedbackType

string

filters?

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.feedbackSource?

string

filters.feedbackType?

string | string[]

filters.feedbackUserId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy?

string[]

interval

"1m" | "5m" | "15m" | "1h" | "1d"

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getFeedbackTimeSeries

getInfrastructureStatus()

getInfrastructureStatus(): Promise<InfrastructureStatusResponse>

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

Returns

Promise<InfrastructureStatusResponse>

Promise containing infrastructure status

Inherited from

MastraClient.getInfrastructureStatus

getItemHistory()

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

Lists versions for a dataset item

Parameters

datasetId

string

itemId

string

Returns

Promise<{ history: DatasetItemVersionResponse[]; }>

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<ServerDetailInfo>

Retrieves detailed information for a specific MCP server.

Parameters

serverId

string

The ID of the MCP server to retrieve.

params?

Optional parameters, e.g., specific version.

version?

string

Returns

Promise<ServerDetailInfo>

Promise containing the detailed MCP server information.

Inherited from

MastraClient.getMcpServerDetails

getMcpServerResources()

getMcpServerResources(serverId): Promise<{ resources: object[]; }>

Lists resources available on an MCP server.

Parameters

serverId

string

The ID of the MCP server.

Returns

Promise<{ resources: object[]; }>

Promise containing the list of resources.

Inherited from

MastraClient.getMcpServerResources

getMcpServers()

getMcpServers(params?): Promise<McpServerListResponse>

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<McpServerListResponse>

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<McpServerToolListResponse>

Retrieves a list of tools for a specific MCP server.

Parameters

serverId

string

The ID of the MCP server.

Returns

Promise<McpServerToolListResponse>

Promise containing the list of tools.

Inherited from

MastraClient.getMcpServerTools

getMemoryConfig()

getMemoryConfig(params): Promise<{ config: { lastMessages?: number | false; 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?: any; workingMemory?: any; } | 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; 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?: any; workingMemory?: any; } | 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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

comparePeriod?

"previous_period" | "previous_day" | "previous_week"

distinctColumn?

filters?

{ costUnit?: string; entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; labels?: Record<string, string>; model?: string; name?: string[]; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; provider?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.costUnit?

string

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.labels?

Record<string, string>

filters.model?

string

filters.name?

string[]

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.provider?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

name

string[]

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

distinctColumn?

filters?

filters.costUnit?

string

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.labels?

Record<string, string>

filters.model?

string

filters.name?

string[]

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.provider?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy

string[]

limit?

number

name

string[]

orderDirection?

"ASC" | "DESC"

Returns

Promise<{ groups: object[]; }>

Inherited from

MastraClient.getMetricBreakdown

getMetricLabelKeys()

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

Returns distinct label keys for a given metric.

Parameters

params

metricName

string

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

labelKey

string

limit?

number

metricName

string

prefix?

string

Returns

Promise<{ values: string[]; }>

Inherited from

MastraClient.getMetricLabelValues

getMetricNames()

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

Returns distinct metric names with optional prefix filtering.

Parameters

params?

limit?

number

prefix?

string

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

filters?

filters.costUnit?

string

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.labels?

Record<string, string>

filters.model?

string

filters.name?

string[]

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.provider?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

interval

"1m" | "5m" | "15m" | "1h" | "1d"

name

string

percentiles

number[]

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

distinctColumn?

filters?

filters.costUnit?

string

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.labels?

Record<string, string>

filters.model?

string

filters.name?

string[]

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.provider?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy?

string[]

interval

"1m" | "5m" | "15m" | "1h" | "1d"

name

string[]

Returns

Promise<{ series: object[]; }>

Inherited from

MastraClient.getMetricTimeSeries

getObservationalMemory()

getObservationalMemory(params): Promise<{ history?: object[]; record: { activeObservations: string; 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; 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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

comparePeriod?

"previous_period" | "previous_day" | "previous_week"

filters?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; scorerId?: string | string[]; scoreSource?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.scorerId?

string | string[]

filters.scoreSource?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

scorerId

string

scoreSource?

string

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

filters?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; scorerId?: string | string[]; scoreSource?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.scorerId?

string | string[]

filters.scoreSource?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy

string[]

scorerId

string

scoreSource?

string

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

filters?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; scorerId?: string | string[]; scoreSource?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.scorerId?

string | string[]

filters.scoreSource?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

interval

"1m" | "5m" | "15m" | "1h" | "1d"

percentiles

number[]

scorerId

string

scoreSource?

string

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

aggregation

"min" | "max" | "sum" | "avg" | "count" | "count_distinct" | "last"

filters?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; scorerId?: string | string[]; scoreSource?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.scorerId?

string | string[]

filters.scoreSource?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: Date; endExclusive?: boolean; start?: Date; startExclusive?: boolean; }

filters.timestamp.end?

Date

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

Date

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

groupBy?

string[]

interval

"1m" | "5m" | "15m" | "1h" | "1d"

scorerId

string

scoreSource?

string

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?: Record<string, unknown> | null; createdAt: Date; endedAt?: Date | null; entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; entityVersionId?: string | null; environment?: string | null; error?: unknown; experimentId?: string | null; input?: unknown; isEvent: boolean; links?: unknown[] | null; metadata?: Record<string, unknown> | null; name: string; organizationId?: string | null; output?: unknown; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; parentSpanId?: string | null; requestContext?: Record<string, unknown> | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanId: string; spanType: SpanType; startedAt: Date; tags?: string[] | null; threadId?: string | null; traceId: string; updatedAt: Date | 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?: Record<string, unknown> | null; createdAt: Date; endedAt?: Date | null; entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; entityVersionId?: string | null; environment?: string | null; error?: unknown; experimentId?: string | null; input?: unknown; isEvent: boolean; links?: unknown[] | null; metadata?: Record<string, unknown> | null; name: string; organizationId?: string | null; output?: unknown; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; parentSpanId?: string | null; requestContext?: Record<string, unknown> | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanId: string; spanType: SpanType; startedAt: Date; tags?: string[] | null; threadId?: string | null; traceId: string; updatedAt: Date | 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<StoredWorkspaceResponse>

Gets a specific stored workspace by ID

Parameters

id

string

The workspace ID

Returns

Promise<StoredWorkspaceResponse>

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: "database" | "filesystem" | "source-provider" | "unavailable"; unavailableReason?: string; }; isDev: boolean; observabilityEnabled: boolean; observabilityRuntimeStrategy?: "realtime" | "batch-with-updates" | "insert-only" | "event-sourced"; 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: "database" | "filesystem" | "source-provider" | "unavailable"; unavailableReason?: string; }; isDev: boolean; observabilityEnabled: boolean; observabilityRuntimeStrategy?: "realtime" | "batch-with-updates" | "insert-only" | "event-sourced"; 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?

entityType?

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

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

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<{ hasMore: boolean; page: number; perPage: number; total: number; uiMessages: object[]; }>

Fetch one page of thread history from GET ${basePath}/route/history. Messages come back oldest -> newest so the caller can prepend them to a live transcript. threadId targets a specific conversation (sent as the ?threadId= query so it doesn’t depend on shared client state); omit it to read the per-session cookie thread.

Parameters

options?

agentId?

string

page?

number

perPage?

number

signal?

AbortSignal

threadId?

string

Returns

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

installBuilderRegistrySkill()

installBuilderRegistrySkill(registryId, body): Promise<BuilderRegistryInstallResponse>

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

BuilderRegistryInstallBody

Returns

Promise<BuilderRegistryInstallResponse>

Inherited from

MastraClient.installBuilderRegistrySkill

listAgentControllers()

listAgentControllers(): Promise<object[]>

Lists the agent controllers hosted on the connected Mastra instance.

Returns

Promise<object[]>

Promise containing an array of agent controller identifiers

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" | "startedAt" | "suspendedAt" | "completedAt"

fromDate?

Date

orderBy?

"createdAt" | "startedAt" | "suspendedAt" | "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?

{ endedAt?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; entityVersionId?: string | null; environment?: string | null; experimentId?: string | null; metadata?: Record<string, unknown> | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanType?: AGENT_RUN | SCORER_RUN | SCORER_STEP | GENERIC | MODEL_GENERATION | MODEL_STEP | MODEL_INFERENCE | MODEL_CHUNK | MCP_TOOL_CALL | PROCESSOR_RUN | TOOL_CALL | CLIENT_TOOL_CALL | WORKFLOW_RUN | WORKFLOW_STEP | WORKFLOW_CONDITIONAL | WORKFLOW_CONDITIONAL_EVAL | WORKFLOW_PARALLEL | WORKFLOW_LOOP | WORKFLOW_SLEEP | WORKFLOW_WAIT_EVENT | MEMORY_OPERATION | WORKSPACE_ACTION | RAG_INGESTION | RAG_EMBEDDING | RAG_VECTOR_OPERATION | RAG_ACTION | GRAPH_ACTION | MAPPING; startedAt?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; status?: SUCCESS | ERROR | RUNNING; tags?: string[] | null; threadId?: string | null; traceId?: string; userId?: string | null; }

filters.endedAt?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.endedAt.end?

unknown

filters.endedAt.endExclusive?

boolean

filters.endedAt.start?

unknown

filters.endedAt.startExclusive?

boolean

filters.entityId?

string | null

filters.entityName?

string | null

filters.entityType?

filters.entityVersionId?

string | null

filters.environment?

string | null

filters.experimentId?

string | null

filters.metadata?

Record<string, unknown> | null

filters.organizationId?

string | null

filters.parentEntityId?

string | null

filters.parentEntityName?

string | null

filters.parentEntityType?

filters.parentEntityVersionId?

string | null

filters.requestId?

string | null

filters.resourceId?

string | null

filters.rootEntityId?

string | null

filters.rootEntityName?

string | null

filters.rootEntityType?

filters.rootEntityVersionId?

string | null

filters.runId?

string | null

filters.scope?

Record<string, unknown> | null

filters.serviceName?

string | null

filters.sessionId?

string | null

filters.source?

string | null

filters.spanType?

filters.startedAt?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.startedAt.end?

unknown

filters.startedAt.endExclusive?

boolean

filters.startedAt.start?

unknown

filters.startedAt.startExclusive?

boolean

filters.status?

SUCCESS | ERROR | RUNNING

filters.tags?

string[] | null

filters.threadId?

string | null

filters.traceId?

string

filters.userId?

string | null

limit?

unknown

mode?

"page" | "delta"

orderBy?

{ direction?: "ASC" | "DESC"; field?: "endedAt" | "startedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"endedAt" | "startedAt"

pagination?

{ page?: unknown; perPage?: unknown; }

pagination.page?

unknown

pagination.perPage?

unknown

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<ListBuilderRegistriesResponse>

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<ListBuilderRegistriesResponse>

Inherited from

MastraClient.listBuilderRegistries

listDatasetExperimentResults()

listDatasetExperimentResults(datasetId, experimentId, pagination?): Promise<{ pagination: PaginationInfo; results: DatasetExperimentResult[]; }>

Lists results for a dataset experiment

Parameters

datasetId

string

experimentId

string

pagination?

page?

number

perPage?

number

Returns

Promise<{ pagination: PaginationInfo; results: DatasetExperimentResult[]; }>

Inherited from

MastraClient.listDatasetExperimentResults

listDatasetExperiments()

listDatasetExperiments(datasetId, pagination?): Promise<{ experiments: DatasetExperiment[]; pagination: PaginationInfo; }>

Lists experiments for a dataset

Parameters

datasetId

string

pagination?

page?

number

perPage?

number

Returns

Promise<{ experiments: DatasetExperiment[]; pagination: PaginationInfo; }>

Inherited from

MastraClient.listDatasetExperiments

listDatasetItems()

listDatasetItems(datasetId, params?): Promise<{ items: DatasetItem[]; pagination: PaginationInfo; }>

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

Parameters

datasetId

string

params?

page?

number

perPage?

number

search?

string

version?

number | null

Returns

Promise<{ items: DatasetItem[]; pagination: PaginationInfo; }>

Inherited from

MastraClient.listDatasetItems

listDatasets()

listDatasets(pagination?): Promise<{ datasets: DatasetRecord[]; pagination: PaginationInfo; }>

Lists all datasets with optional pagination

Parameters

pagination?

page?

number

perPage?

number

Returns

Promise<{ datasets: DatasetRecord[]; pagination: PaginationInfo; }>

Inherited from

MastraClient.listDatasets

listDatasetVersions()

listDatasetVersions(datasetId, pagination?): Promise<{ pagination: PaginationInfo; versions: DatasetVersionResponse[]; }>

Lists versions for a dataset

Parameters

datasetId

string

pagination?

page?

number

perPage?

number

Returns

Promise<{ pagination: PaginationInfo; versions: DatasetVersionResponse[]; }>

Inherited from

MastraClient.listDatasetVersions

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(pagination?): Promise<{ experiments: DatasetExperiment[]; pagination: PaginationInfo; }>

Lists all experiments across all datasets

Parameters

pagination?

page?

number

perPage?

number

Returns

Promise<{ experiments: DatasetExperiment[]; pagination: PaginationInfo; }>

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?

any

limit?

unknown

mode?

"page" | "delta"

orderBy?

{ direction?: "ASC" | "DESC"; field?: "timestamp"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"timestamp"

pagination?

{ page?: unknown; perPage?: unknown; }

pagination.page?

unknown

pagination.perPage?

unknown

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?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; level?: "error" | "debug" | "info" | "warn" | "fatal" | ("error" | "debug" | "info" | "warn" | "fatal")[]; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.level?

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.timestamp.end?

unknown

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

unknown

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

limit?

unknown

mode?

"page" | "delta"

orderBy?

{ direction?: "ASC" | "DESC"; field?: "timestamp"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"timestamp"

pagination?

{ page?: unknown; perPage?: unknown; }

pagination.page?

unknown

pagination.perPage?

unknown

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<{ transports: string[]; }>

List of all log transports

Returns

Promise<{ transports: string[]; }>

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, GetProcessorResponse>>

Retrieves all available processors

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<Record<string, GetProcessorResponse>>

Promise containing map of processor IDs to processor details

Inherited from

MastraClient.listProcessors

listSchedules()

listSchedules(params?): Promise<ListSchedulesResponse>

Lists workflow schedules with optional filtering by workflowId or status.

Parameters

params?

ListSchedulesParams

Returns

Promise<ListSchedulesResponse>

Inherited from

MastraClient.listSchedules

listScheduleTriggers()

listScheduleTriggers(scheduleId, params?): Promise<ListScheduleTriggersResponse>

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

Parameters

scheduleId

string

params?

ListScheduleTriggersParams

Returns

Promise<ListScheduleTriggersResponse>

Inherited from

MastraClient.listScheduleTriggers

listScorers()

listScorers(requestContext?): Promise<Record<string, GetScorerResponse>>

Retrieves all available scorers

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<Record<string, GetScorerResponse>>

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?

{ entityName?: string; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; entityVersionId?: string; environment?: string; executionSource?: string; experimentId?: string; organizationId?: string; parentEntityName?: string; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; parentEntityVersionId?: string; requestId?: string; resourceId?: string; rootEntityName?: string; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY; rootEntityVersionId?: string; runId?: string; scorerId?: string | string[]; scoreSource?: string; serviceName?: string; sessionId?: string; source?: string; spanId?: string; tags?: string[]; threadId?: string; timestamp?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; traceId?: string; userId?: string; }

filters.entityName?

string

filters.entityType?

filters.entityVersionId?

string

filters.environment?

string

filters.executionSource?

string

filters.experimentId?

string

filters.organizationId?

string

filters.parentEntityName?

string

filters.parentEntityType?

filters.parentEntityVersionId?

string

filters.requestId?

string

filters.resourceId?

string

filters.rootEntityName?

string

filters.rootEntityType?

filters.rootEntityVersionId?

string

filters.runId?

string

filters.scorerId?

string | string[]

filters.scoreSource?

string

filters.serviceName?

string

filters.sessionId?

string

filters.source?

string

filters.spanId?

string

filters.tags?

string[]

filters.threadId?

string

filters.timestamp?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.timestamp.end?

unknown

filters.timestamp.endExclusive?

boolean

filters.timestamp.start?

unknown

filters.timestamp.startExclusive?

boolean

filters.traceId?

string

filters.userId?

string

limit?

unknown

mode?

"page" | "delta"

orderBy?

{ direction?: "ASC" | "DESC"; field?: "score" | "timestamp"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"score" | "timestamp"

pagination?

{ page?: unknown; perPage?: unknown; }

pagination.page?

unknown

pagination.perPage?

unknown

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

ListScoresByEntityIdParams

Parameters containing entity ID, type, and pagination options

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

ListScoresByRunIdParams

Parameters containing run ID and pagination options

Returns

Promise<ListScoresResponse>

Promise containing scores and pagination info

Inherited from

MastraClient.listScoresByRunId

listScoresByScorerId()

listScoresByScorerId(params): Promise<ListScoresResponse>

Parameters

params

ListScoresByScorerIdParams

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<ListStoredAgentsResponse>

Lists all stored agents with optional pagination

Parameters

params?

ListStoredAgentsParams

Optional pagination and ordering parameters

Returns

Promise<ListStoredAgentsResponse>

Promise containing paginated list of stored agents

Inherited from

MastraClient.listStoredAgents

listStoredMCPClients()

listStoredMCPClients(params?): Promise<ListStoredMCPClientsResponse>

Lists all stored MCP clients with optional pagination

Parameters

params?

ListStoredMCPClientsParams

Optional pagination and ordering parameters

Returns

Promise<ListStoredMCPClientsResponse>

Promise containing paginated list of stored MCP clients

Inherited from

MastraClient.listStoredMCPClients

listStoredPromptBlocks()

listStoredPromptBlocks(params?): Promise<ListStoredPromptBlocksResponse>

Lists all stored prompt blocks with optional pagination

Parameters

params?

ListStoredPromptBlocksParams

Optional pagination and ordering parameters

Returns

Promise<ListStoredPromptBlocksResponse>

Promise containing paginated list of stored prompt blocks

Inherited from

MastraClient.listStoredPromptBlocks

listStoredScorers()

listStoredScorers(params?): Promise<ListStoredScorersResponse>

Lists all stored scorer definitions with optional pagination

Parameters

params?

ListStoredScorersParams

Optional pagination and ordering parameters

Returns

Promise<ListStoredScorersResponse>

Promise containing paginated list of stored scorer definitions

Inherited from

MastraClient.listStoredScorers

listStoredSkills()

listStoredSkills(params?): Promise<ListStoredSkillsResponse>

Lists all stored skills with optional pagination

Parameters

params?

ListStoredSkillsParams

Optional pagination and ordering parameters

Returns

Promise<ListStoredSkillsResponse>

Promise containing paginated list of stored skills

Inherited from

MastraClient.listStoredSkills

listStoredWorkspaces()

listStoredWorkspaces(params?): Promise<ListStoredWorkspacesResponse>

Lists stored workspace configurations from the database

Parameters

params?

ListStoredWorkspacesParams

Optional filter and pagination parameters

Returns

Promise<ListStoredWorkspacesResponse>

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?

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

agentId?

string

includeSystemReminders?

boolean

networkId?

string

requestContext?

RequestContext<unknown> | Record<string, any>

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, GetToolResponse>>

Retrieves all available tools

Parameters

requestContext?

RequestContext<unknown> | Record<string, any>

Optional request context to pass as query parameter

Returns

Promise<Record<string, GetToolResponse>>

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?

{ endedAt?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; entityId?: string | null; entityName?: string | null; entityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; entityVersionId?: string | null; environment?: string | null; experimentId?: string | null; hasChildError?: any; metadata?: Record<string, unknown> | null; organizationId?: string | null; parentEntityId?: string | null; parentEntityName?: string | null; parentEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; parentEntityVersionId?: string | null; requestId?: string | null; resourceId?: string | null; rootEntityId?: string | null; rootEntityName?: string | null; rootEntityType?: AGENT | SCORER | RAG_INGESTION | TRAJECTORY | INPUT_PROCESSOR | INPUT_STEP_PROCESSOR | OUTPUT_PROCESSOR | OUTPUT_STEP_PROCESSOR | WORKFLOW_STEP | TOOL | WORKFLOW_RUN | MEMORY | null; rootEntityVersionId?: string | null; runId?: string | null; scope?: Record<string, unknown> | null; serviceName?: string | null; sessionId?: string | null; source?: string | null; spanType?: AGENT_RUN | SCORER_RUN | SCORER_STEP | GENERIC | MODEL_GENERATION | MODEL_STEP | MODEL_INFERENCE | MODEL_CHUNK | MCP_TOOL_CALL | PROCESSOR_RUN | TOOL_CALL | CLIENT_TOOL_CALL | WORKFLOW_RUN | WORKFLOW_STEP | WORKFLOW_CONDITIONAL | WORKFLOW_CONDITIONAL_EVAL | WORKFLOW_PARALLEL | WORKFLOW_LOOP | WORKFLOW_SLEEP | WORKFLOW_WAIT_EVENT | MEMORY_OPERATION | WORKSPACE_ACTION | RAG_INGESTION | RAG_EMBEDDING | RAG_VECTOR_OPERATION | RAG_ACTION | GRAPH_ACTION | MAPPING; startedAt?: { end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }; status?: SUCCESS | ERROR | RUNNING; tags?: string[] | null; threadId?: string | null; traceId?: string; userId?: string | null; }

filters.endedAt?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.endedAt.end?

unknown

filters.endedAt.endExclusive?

boolean

filters.endedAt.start?

unknown

filters.endedAt.startExclusive?

boolean

filters.entityId?

string | null

filters.entityName?

string | null

filters.entityType?

filters.entityVersionId?

string | null

filters.environment?

string | null

filters.experimentId?

string | null

filters.hasChildError?

any

filters.metadata?

Record<string, unknown> | null

filters.organizationId?

string | null

filters.parentEntityId?

string | null

filters.parentEntityName?

string | null

filters.parentEntityType?

filters.parentEntityVersionId?

string | null

filters.requestId?

string | null

filters.resourceId?

string | null

filters.rootEntityId?

string | null

filters.rootEntityName?

string | null

filters.rootEntityType?

filters.rootEntityVersionId?

string | null

filters.runId?

string | null

filters.scope?

Record<string, unknown> | null

filters.serviceName?

string | null

filters.sessionId?

string | null

filters.source?

string | null

filters.spanType?

filters.startedAt?

{ end?: unknown; endExclusive?: boolean; start?: unknown; startExclusive?: boolean; }

filters.startedAt.end?

unknown

filters.startedAt.endExclusive?

boolean

filters.startedAt.start?

unknown

filters.startedAt.startExclusive?

boolean

filters.status?

SUCCESS | ERROR | RUNNING

filters.tags?

string[] | null

filters.threadId?

string | null

filters.traceId?

string

filters.userId?

string | null

limit?

unknown

mode?

"page" | "delta"

orderBy?

{ direction?: "ASC" | "DESC"; field?: "endedAt" | "startedAt"; }

orderBy.direction?

"ASC" | "DESC"

orderBy.field?

"endedAt" | "startedAt"

pagination?

{ page?: unknown; perPage?: unknown; }

pagination.page?

unknown

pagination.perPage?

unknown

Returns

Promise containing paginated traces and pagination info

Inherited from

MastraClient.listTraces

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

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

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[]>

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

readMcpServerResource()

readMcpServerResource(serverId, uri): Promise<{ contents: object[]; }>

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<{ contents: object[]; }>

Promise containing the resource content.

Inherited from

MastraClient.readMcpServerResource

removeThread()

removeThread(threadId, options?): Promise<{ agentId: string; deleted: boolean; ok: true; threadId: string; }>

Delete a single conversation thread by id via the plugin’s own DELETE ${basePath}/threads route (named removeThread to avoid clashing with the inherited MastraClient.deleteThread, which hits Mastra’s stock thread route rather than our OBO-scoped, custom mount). The id is sent as the thread-selection header for this one call, so the sidebar can remove any thread while the user stays on another (routing is per call, never shared). Idempotent: deleting an unknown / already-removed thread reports deleted: false without erroring.

Parameters

threadId

string

options?

agentId?

string

signal?

AbortSignal

Returns

Promise<{ agentId: string; deleted: boolean; ok: true; threadId: string; }>

renameThread()

renameThread(threadId, title, options?): Promise<{ agentId: string; ok: true; thread: { createdAt: string; id: string; metadata?: unknown; resourceId: string; title?: string; updatedAt: string; }; }>

Rename a single conversation thread via the plugin’s own PATCH ${basePath}/threads route. The id travels as the thread-selection header for this one call (mirroring removeThread, so the sidebar can rename any thread; routing is per call, never shared) and the new title rides in the JSON body. The server enforces ownership and echoes back the updated thread, so the caller can reflect the new title immediately. Throws on an unknown / unowned thread (HTTP 404).

Parameters

threadId

string

title

string

options?

agentId?

string

signal?

AbortSignal

Returns

Promise<{ agentId: string; ok: true; thread: { createdAt: string; id: string; metadata?: unknown; resourceId: string; title?: string; updatedAt: string; }; }>

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

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; }>

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

Parameters

params

scorerName

string

targets

object[]

Returns

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

Inherited from

MastraClient.score

searchBuilderRegistry()

searchBuilderRegistry(registryId, params): Promise<BuilderRegistrySearchResponse>

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<BuilderRegistrySearchResponse>

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 an agent stream for one conversation turn, routed and cancelled PER CALL. Posts to the agent /stream route with this run’s own thread id + model as request headers and its own AbortSignal on the fetch, so many threads can stream at once and aborting one leaves the others untouched. Reads the SSE directly (like the tool-approval streams) rather than through the inherited agent.stream(), whose shared-client headers and single client-level abort signal can’t isolate concurrent runs.

Parameters

params

agentId

string

messages

object[]

model?

string

runId

string

signal?

AbortSignal

threadId?

string

Returns

Promise<MastraStreamResponse>

streamBackgroundTasks()

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

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<any>>

Inherited from

MastraClient.streamBackgroundTasks

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[]>

threads()

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

Fetch one page of the caller’s conversation threads from GET ${basePath}/threads, newest first. Used to render the conversation list / sidebar so the user can switch between the threads they own for this resource. Scoped server-side to the caller’s resource id, so it only ever returns the user’s own conversations.

Parameters

options?

agentId?

string

page?

number

perPage?

number

signal?

AbortSignal

Returns

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

triggerDatasetExperiment()

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

Triggers a new dataset experiment

Parameters

params

TriggerDatasetExperimentParams

Returns

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

Inherited from

MastraClient.triggerDatasetExperiment

updateDataset()

updateDataset(params): Promise<DatasetRecord>

Updates a dataset

Parameters

params

UpdateDatasetParams

Returns

Promise<DatasetRecord>

Inherited from

MastraClient.updateDataset

updateDatasetExperimentResult()

updateDatasetExperimentResult(params): Promise<DatasetExperimentResult>

Updates an experiment result’s status and/or tags

Parameters

params

UpdateExperimentResultParams

Returns

Promise<DatasetExperimentResult>

Inherited from

MastraClient.updateDatasetExperimentResult

updateDatasetItem()

updateDatasetItem(params): Promise<DatasetItem>

Updates a dataset item

Parameters

params

UpdateDatasetItemParams

Returns

Promise<DatasetItem>

Inherited from

MastraClient.updateDatasetItem

updateExperimentResult()

updateExperimentResult(params): Promise<DatasetExperimentResult>

Updates the status and/or tags on an experiment result

Parameters

params

UpdateExperimentResultParams

Returns

Promise<DatasetExperimentResult>

Inherited from

MastraClient.updateExperimentResult

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