Evals

Launch an eval

Changed on Oct 30, 2026

Launch an evaluation. This is the API-equivalent of the Eval function that is built into the Braintrust SDK. In the Eval API, you provide pointers to a dataset, task function, and scoring functions. The API will then run the evaluation, create an experiment, and return the results along with a link to the experiment. To learn more about evals, see the Evals guide.

post/v1/eval

Request

Base URL
https://api.braintrust.dev
Auth
- HTTP bearer
- or none

Request body

project_idstring required

Unique identifier for the project to run the eval in

namestring

The name of the eval to run when multiple evals available

parametersobject

Values for any parameters used in the eval

experiment_namestring

An optional name for the experiment created by this eval. If it conflicts with an existing experiment, it will be suffixed with a unique identifier.

metadataobject

Optional experiment-level metadata to store about the evaluation. You can later use this to slice & dice across experiments.

streamboolean

Whether to stream the results of the eval. If true, the request will return two events: one to indicate the experiment has started, and another upon completion. If false, the request will return the evaluation's summary upon completion.

trial_countnumber nullable

The number of times to run the evaluator per input. This is useful for evaluating applications that have non-deterministic behavior and gives you both a stronger aggregate measure and a sense of the variance in the results.

is_publicboolean nullable

Whether the experiment should be public. Defaults to false.

timeoutnumber nullable

The maximum duration, in milliseconds, to run the evaluation. There is no timeout by default.

max_concurrencynumber nullable

The maximum number of tasks/scorers that will be run concurrently. Defaults to 10. If null is provided, no max concurrency will be used.

base_experiment_namestring nullable

An optional experiment name to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

base_experiment_idstring nullable

An optional experiment id to use as a base. If specified, the new experiment will be summarized and compared to this experiment.

strictboolean nullable

If true, throw an error if one of the variables in the prompt is not present in the input

stop_tokenstring nullable

The token to stop the run

extra_messagesstring

A template path of extra messages to append to the conversion. These messages will be appended to the end of the conversation, after the last message.

tagsstring[]

Optional tags that will be added to the experiment.

mcp_authobject

endpoint_namestring nullable

Name of the AI provider secret to pin this run to.

Response

Eval launch response

project_namestring required

Name of the project that the experiment belongs to

experiment_namestring required

Name of the experiment

project_urlstring uri required

URL to the project's page in the Braintrust app

experiment_urlstring uri required

URL to the experiment's page in the Braintrust app

comparison_experiment_namestring nullable

The experiment which scores are baselined against

scoresobject nullable

Summary of the experiment's scores

metricsobject nullable

Summary of the experiment's metrics

Changes

Oct 30, 20268f5039399f77 Revision changes
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property / became not nullable
- breaking
  the request property / became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property //// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property ///// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ///////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////////// became not nullable
- breaking
  the request property //////////////// became not nullable
- breaking
  the request property ////////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property /////////////// became not nullable
- breaking
  the request property /////////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ///////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////////// became not nullable
- breaking
  the request property //////////////// became not nullable
- breaking
  the request property ////////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property /////////////// became not nullable
- breaking
  the request property /////////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property ///////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property //// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property ///////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ////////// became not nullable
- breaking
  the request property ////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property //// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /////// became not nullable
- breaking
  the request property /////////// became not nullable
- breaking
  the request property ///////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property ////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property ////////// became not nullable
- breaking
  the request property ////////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property //////// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property /// became not nullable
- breaking
  the request property // became not nullable
- breaking
  the request property became not nullable
- breaking
  the request property became not nullable
- breaking
  removed the enum value undefined of the request property ///////
- breaking
  removed the enum value undefined of the request property ///////////
- breaking
  removed the enum value undefined of the request property ///////
- breaking
  removed the enum value undefined of the request property ///////////////
- breaking
  removed the enum value undefined of the request property ////////////
- breaking
  removed the enum value undefined of the request property ///////
- breaking
  removed the enum value undefined of the request property ///////////////
- breaking
  removed the enum value undefined of the request property ////////////
- breaking
  removed the enum value undefined of the request property //
- breaking
  removed the enum value undefined of the request property //////
- breaking
  removed the enum value undefined of the request property //
- breaking
  removed the enum value undefined of the request property //////////
- breaking
  removed the enum value undefined of the request property ///////
- breaking
  removed the enum value undefined of the request property //
- breaking
  removed the enum value undefined of the request property //////////
- breaking
  removed the enum value undefined of the request property ///////
Oct 29, 20266409b3f2bde5 Revision changes
- info
  added the new optional request property //

Operation history (28 revisions)

Launch an eval

Request

Request body

Response 200OK

Changes

Response