Skip to main content

dataset.listExperiments()

Added in: @mastra/core@1.4.0

Lists experiments (runs) for this dataset with optional filters and pagination. Filters are applied at the storage layer, so results are always scoped to the current dataset.

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' })

// Basic pagination
const { experiments, pagination } = await dataset.listExperiments({ page: 0, perPage: 10 })

// Filter to a specific agent version — useful for baseline vs variant comparisons
const { experiments: v2Runs } = await dataset.listExperiments({
  targetType: 'agent',
  targetId: 'my-agent',
  agentVersion: 'v2',
  status: 'completed',
})

for (const exp of experiments) {
  console.log(`${exp.id}: ${exp.status} (${exp.succeededCount}/${exp.totalItems})`)
}

Parameters
Direct link to Parameters

targetType?:

'agent' | 'workflow' | 'scorer' | 'processor'
Restrict results to experiments run against this target type.

targetId?:

string
Restrict results to experiments run against this target ID.

agentVersion?:

string
Restrict results to experiments recorded against this agent version. Useful for distinguishing baseline from variant runs.

status?:

'pending' | 'running' | 'completed' | 'failed'
Restrict results to experiments in this status.

filters?:

ExperimentTenancyFilters
Multi-tenant scoping filters (organizationId, projectId). Forwarded to the storage layer.

page?:

number
Page number. Defaults to 0.

perPage?:

number
Number of experiments per page. Defaults to 20.

Returns
Direct link to Returns

result:

Promise<object>
Paginated experiment list.
object

experiments:

Experiment[]
Array of experiment records.
Experiment

id:

string
Unique experiment ID.

name?:

string
Display name.

description?:

string
Description.

metadata?:

Record<string, unknown>
Arbitrary metadata.

datasetId:

string
ID of the parent dataset.

datasetVersion:

number | null
Dataset version used for the experiment.

targetType:

'agent' | 'workflow' | 'scorer' | 'processor'
Type of target used.

targetId:

string
ID of the target used.

status:

'pending' | 'running' | 'completed' | 'failed'
Current status of the experiment.

totalItems:

number
Total number of items.

succeededCount:

number
Number of successful items.

failedCount:

number
Number of failed items.

skippedCount:

number
Number of skipped items.

startedAt:

Date | null
When the experiment started.

completedAt:

Date | null
When the experiment completed.

createdAt:

Date
When the experiment record was created.

updatedAt:

Date
When the experiment record was last updated.

pagination:

PaginationInfo
Pagination metadata with total, page, perPage, and hasMore.
On this page