Skip to main content

dataset.startExperimentAsync()

Added in: @mastra/core@1.4.0

Starts an experiment asynchronously (fire-and-forget). Returns immediately with the experiment ID and a 'pending' status. The experiment runs in the background.

Usage example
Direct link to Usage example

import { Mastra } from '@mastra/core'

const mastra = new Mastra({/* storage config */})

const dataset = await mastra.datasets.get({ id: 'dataset-id' })

// Start experiment without waiting
const { experimentId, status } = await dataset.startExperimentAsync({
  targetType: 'agent',
  targetId: 'my-agent',
  scorers: ['accuracy'],
})

console.log(`Experiment ${experimentId} started with status: ${status}`)

// Check progress later
const experiment = await dataset.getExperiment({ experimentId })
console.log(`Current status: ${experiment.status}`)

Parameters
Direct link to Parameters

Takes the same StartExperimentConfig as dataset.startExperiment().

When persistence.experiments is set to 'none', startExperimentAsync() doesn't persist an experiment record, progress updates, or item results. Score persistence remains controlled separately by persistence.scores. Without an experiment event observer, the run is fire-and-forget, and the experiment API can't report whether it completed or failed.

Use synchronous startExperiment() when the caller needs the returned summary. An experiment event observer can receive lifecycle events and the terminal summary.

Returns
Direct link to Returns

result:

Promise<object>
Immediate response with experiment ID.
object

experimentId:

string
Unique ID of the created experiment.

status:

'pending'
Always 'pending' since the experiment hasn't started executing yet.
On this page