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

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 })
if (!experiment) throw new Error('Experiment not found')
console.log(`Current status: ${experiment.status}`)

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

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.

Related

• dataset.startExperiment()
• dataset.getExperiment()