Skip to main content

dataset.finalizeExperiment()

Added in: @mastra/core@1.61.0

Finalizes a caller-driven experiment created with createExperiment(), with or without a target. Mastra computes the final counts server-side from the persisted result rows and marks the experiment 'completed'. An experiment that's already 'failed' is returned unchanged and stays failed. The caller never tracks completion bookkeeping.

Counts are per item, so succeededCount + failedCount + skippedCount === totalItems even when items have multiple attempts:

  • succeededCount: items where at least one attempt completed without an error
  • failedCount: items that were submitted but where every attempt errored
  • skippedCount: dataset items that were never submitted (any attempt)

Attempt-level detail remains available through listExperimentResults().

Finalization is idempotent: calling it on an already completed or failed experiment returns the stored record without recomputing.

Usage example
Direct link to Usage example

const experiment = await dataset.finalizeExperiment({ experimentId })

console.log(experiment.status) // 'completed'
console.log(experiment.succeededCount)
console.log(experiment.failedCount)
console.log(experiment.skippedCount)

Parameters
Direct link to Parameters

experimentId:

string
ID of the experiment to finalize.

Returns
Direct link to Returns

Returns a Promise<Experiment>, the updated experiment record with final status, counts, and completedAt timestamp.

On this page