# dataset.startExperiment()

**Added in:** `@mastra/core@1.4.0`

Runs an experiment on the dataset and waits for completion. Executes all items against a target (agent, workflow, or scorer) with optional scoring.

## Usage example

```typescript
import { Mastra } from "@mastra/core";

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

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

// Run against a registered agent with scorers
const summary = await dataset.startExperiment({
  targetType: "agent",
  targetId: "my-agent",
  scorers: ["accuracy", "relevancy"],
  maxConcurrency: 10,
});

console.log(`${summary.succeededCount}/${summary.totalItems} succeeded`);
console.log(`Status: ${summary.status}`);
```

## Parameters

**targetType?:** (`'agent' | 'workflow' | 'scorer'`): Type of registered target to run items against. Use with \`targetId\`.

**targetId?:** (`string`): ID of the registered target. Use with \`targetType\`.

**scorers?:** (`(MastraScorer | string)[]`): Scorers to evaluate each result. Pass \`MastraScorer\` instances or registered scorer IDs.

**name?:** (`string`): Display name for the experiment.

**description?:** (`string`): Description of the experiment.

**metadata?:** (`Record<string, unknown>`): Arbitrary metadata for the experiment.

**version?:** (`number`): Pin to a specific dataset version. Defaults to the latest version.

**maxConcurrency?:** (`number`): Maximum concurrent item executions. Defaults to \`5\`.

**signal?:** (`AbortSignal`): AbortSignal for cancelling the experiment.

**itemTimeout?:** (`number`): Per-item execution timeout in milliseconds.

**maxRetries?:** (`number`): Maximum retries per item on failure. Defaults to \`0\` (no retries). Abort errors are never retried.

## Returns

**result:** (`Promise<ExperimentSummary>`): ExperimentSummaryexperimentId:stringUnique ID of the experiment.status:'pending' | 'running' | 'completed' | 'failed'Final status of the experiment.totalItems:numberTotal number of items in the dataset.succeededCount:numberNumber of items that succeeded.failedCount:numberNumber of items that failed.skippedCount:numberNumber of items skipped (e.g., due to abort).completedWithErrors:boolean\`true\` if the run completed but some items failed.startedAt:DateWhen the experiment started.completedAt:DateWhen the experiment completed.results:ItemWithScores\[]All item results with their scores.ItemWithScoresitemId:stringID of the dataset item.itemVersion:numberDataset version of the item when executed.input:unknownInput data passed to the target.output:unknown | nullOutput from the target, or \`null\` if failed.groundTruth:unknown | nullExpected output from the dataset item.error:{ message: string; stack?: string; code?: string } | nullStructured error if execution failed.startedAt:DateWhen item execution started.completedAt:DateWhen item execution completed.retryCount:numberNumber of retry attempts.scores:ScorerResult\[]Results from all scorers for this item.ScorerResultscorerId:stringID of the scorer.scorerName:stringDisplay name of the scorer.score:number | nullComputed score, or \`null\` if the scorer failed.reason:string | nullReason/explanation for the score.error:string | nullError message if the scorer failed.

## Related

- [dataset.startExperimentAsync()](https://mastra.ai/reference/datasets/startExperimentAsync)
- [dataset.listExperiments()](https://mastra.ai/reference/datasets/listExperiments)
- [DatasetsManager.compareExperiments()](https://mastra.ai/reference/datasets/compareExperiments)