Skip to main content

dataset.submitExperimentResult()

Added in: @mastra/core@1.61.0

Submits (or re-submits) one externally computed item result for a target-less experiment created with createExperiment().

Submissions are upserts keyed by (experimentId, itemId, attempt): a retried worker that submits the same key converges on a single row instead of duplicating results. Use a different attempt value to record repeated trials as separate rows.

Usage example
Direct link to Usage example

const result = await dataset.submitExperimentResult({
  experimentId,
  itemId: 'item-1',
  output: { translation: 'Hola' },
  scores: [{ scorerId: 'accuracy', score: 0.92, reason: 'Faithful translation' }],
})

The item must be visible at the experiment's pinned dataset version. Submissions to an experiment that has a target throw EXPERIMENT_HAS_TARGET, which prevents two writers from racing on the same rows. Submissions after finalization throw EXPERIMENT_ALREADY_FINALIZED.

Parameters
Direct link to Parameters

experimentId:

string
ID of the target-less experiment.

itemId:

string
ID of the dataset item this result belongs to.

attempt?:

number
Attempt number for repeated trials. Defaults to 0. Same (experimentId, itemId, attempt) upserts the existing row.

input?:

unknown
Input the worker ran. Defaults to the dataset item's input at the pinned version.

output?:

unknown
Output produced by the external worker.

groundTruth?:

unknown
Expected output. Defaults to the dataset item's ground truth at the pinned version.

error?:

object
Error details (message, optional stack and code) when the item failed.

startedAt?:

Date
When the worker started this item.

completedAt?:

Date
When the worker finished this item.

traceId?:

string
Trace ID linking the result to observability data.

scores?:

array
Externally computed scores (scorerId, score, optional scorerName, reason, metadata). Persisted to the scores store under the experiment, so they appear in comparisons alongside native scorer runs. Score persistence is best-effort and never fails the submission.

Returns
Direct link to Returns

Returns a Promise<ExperimentResult>, the persisted result row, including its id, attempt, and timestamps.

On this page