> Discover all available pages from the documentation index: https://mastra.ai/llms.txt

# 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

```typescript
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

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

**result** (`Promise<object>`): Paginated experiment list.

**result.experiments** (`Experiment[]`): Array of experiment records.

**result.experiments.id** (`string`): Unique experiment ID.

**result.experiments.name** (`string`): Display name.

**result.experiments.description** (`string`): Description.

**result.experiments.metadata** (`Record<string, unknown>`): Arbitrary metadata.

**result.experiments.datasetId** (`string`): ID of the parent dataset.

**result.experiments.datasetVersion** (`number | null`): Dataset version used for the experiment.

**result.experiments.targetType** (`'agent' | 'workflow' | 'scorer' | 'processor'`): Type of target used.

**result.experiments.targetId** (`string`): ID of the target used.

**result.experiments.status** (`'pending' | 'running' | 'completed' | 'failed'`): Current status of the experiment.

**result.experiments.totalItems** (`number`): Total number of items.

**result.experiments.succeededCount** (`number`): Number of successful items.

**result.experiments.failedCount** (`number`): Number of failed items.

**result.experiments.skippedCount** (`number`): Number of skipped items.

**result.experiments.startedAt** (`Date | null`): When the experiment started.

**result.experiments.completedAt** (`Date | null`): When the experiment completed.

**result.experiments.createdAt** (`Date`): When the experiment record was created.

**result.experiments.updatedAt** (`Date`): When the experiment record was last updated.

**result.pagination** (`PaginationInfo`): Pagination metadata with total, page, perPage, and hasMore.