Braintest
POST/v1/experiment

Create experiment

Create a new experiment. If there is an existing experiment in the project with the same name as the one specified in the request, will return the existing experiment unmodified

  • IdempotentThe SDK sends Idempotency-Key, so a retried request is only applied once.

10 body fields

Any desired information about the new experiment object

project_idstringrequired
Unique identifier for the project that the experiment belongs under
namestringoptional
Name of the experiment. Within a project, experiment names are unique
descriptionstringoptional
Textual description of the experiment
repo_infoobjectoptional
Metadata about the state of the repo when the experiment was created
base_exp_idstringoptional
Id of default base experiment to compare against when viewing this experiment
dataset_idstringoptional
Identifier of the linked dataset, or null if the experiment is not linked to a dataset
dataset_versionstringoptional
Version number of the linked dataset the experiment was run against. This can be used to reproduce the experiment after the dataset has been modified.
publicbooleanoptional
Whether or not the experiment is public. Public experiments can be viewed by anybody inside or outside the organization
metadataobjectoptional
User-controlled metadata about the experiment
ensure_newbooleanoptional
Normally, creating an experiment with the same name as an existing experiment will return the existing one un-modified. But if `ensure_new` is true, registration will generate a new experiment with a unique name in case of a conflict.

6 status codes
200Returns the new experiment object
idstringrequired
Unique identifier for the experiment
project_idstringrequired
Unique identifier for the project that the experiment belongs under
namestringrequired
Name of the experiment. Within a project, experiment names are unique
descriptionstringoptional
Textual description of the experiment
createdstringoptional
Date of experiment creation
repo_infoobjectoptional
Metadata about the state of the repo when the experiment was created
commitstringoptional
Commit, taken directly from `repo_info.commit`
base_exp_idstringoptional
Id of default base experiment to compare against when viewing this experiment
deleted_atstringoptional
Date of experiment deletion, or null if the experiment is still active
dataset_idstringoptional
Identifier of the linked dataset, or null if the experiment is not linked to a dataset
dataset_versionstringoptional
Version number of the linked dataset the experiment was run against. This can be used to reproduce the experiment after the dataset has been modified.
publicbooleanrequired
Whether or not the experiment is public. Public experiments can be viewed by anybody inside or outside the organization
user_idstringoptional
Identifies the user who created the experiment
metadataobjectoptional
User-controlled metadata about the experiment
400The request was unacceptable, often due to missing a required parameter
401No valid API key provided
403The API key doesn’t have permissions to perform the request
429Too many requests hit the API too quickly. We recommend an exponential backoff of your requests
500Something went wrong on Braintrust's end. (These are rare.)

Error handling

A 400 is returned: The request was unacceptable, often due to missing a required parameter A 401 is returned: No valid API key provided A 403 is returned: The API key doesn’t have permissions to perform the request A 429 is returned: Too many requests hit the API too quickly. We recommend an exponential backoff of your requests A 500 is returned: Something went wrong on Braintrust's end. (These are rare.)